p4api

Simple Perforce API

Usage no npm install needed!

<script type="module">
  import p4api from 'https://cdn.skypack.dev/p4api';
</script>

README

p4api

With p4api, you can execute Perforce commands according to 4 modes in your choice:

Async command Sync command
Marshal syntax cmd() cmdSync()
Raw syntax rawCmd() rawCmdSync()

Asynchronous command returns a promise wich will be resolved with the Perforce result while sync command is blocked until Perforce has returned a result.

Promise returned with Sync command can be canceled with cancel() method, killing launched p4 process.

Marshal syntax consists to use global -G option allowing to provide input and receive result as a JS object.
Raw syntax uses basic text format.
Note that only login command accepts input parameter (password) as a string in both Marshal and Raw modes.

If P4VC is installed, you will be able to launch any p4vc command with visual() method wich returns a promise wich is resolved when p4vc has closed.

All these method belong to class P4 provided by the module p4api: See detail here

Installation

Get the module from NPM

$ npm install p4api --save

Development

Use build action (npm or yarn) to build lib/p4api.js.

To test it, you need to have installed "Helix Core Apps" and "Helix Versioning Engine" (p4 & p4d).

P4 object

Contructor

import {P4} from "p4api"
const p4 = new P4({p4set:{}, binPath: '', debug: false})

where

  • p4set : a set of P4 variables to apply as context when executing p4 commands:
    • all P4 environnment variables like P4PORT, P4CHARSET, P4USER, P4CLIENT, ...
    • p4api specific option like:
      • P4API_TIMEOUT: timeout in ms for p4 commands process
  • binPath : a path prefix to add to the call for p4 and p4vc
  • debug : if true, display some debug info

Example:

const p4 = new P4({ 
    p4set: {
        P4PORT: "myP4Server:1666",
        P4CHARSET: "utf8",
        P4API_TIMEOUT: 5000},
    binPath: '/usr/sbin/'
})

:information_source: INFO:
Old constructor syntax before V3.4 is still allowed. Ex : p4 = new P4({P4PORT: "myP4Server:1666"})

:warning: WARNING:
P4CLIENT, P4PORT & P4USER will never be overloaded with variable set in a P4CONFIG file

Static Attributs

Name Description
Error Error instance
TimeoutError Error instance

Methods

Change environment variables

setOpts(opt) and addOpts(opt) allow you to set or merge environment variables.

import {P4} from "p4api"
const p4 = new P4({p4set: {P4PORT: "p4server:1666"}})

p4.setOpts({env:{P4PORT: "newServer:1666"}})
p4.addOpts({env:{P4USER: "bob", P4CLIENT="bob_client"}}

Where:

  • opt is the option parameter injected in spawn() function

:warning: WARNING:
In the most current case, use only the field env in opt.
Use other fields than env is not tested !

Marshal syntax commands

cmd(p4Cmd, [input]) and cmdSync(p4Cmd, [input]) allow to execute any p4 command using Marshal syntax (global p4 option -G).

import {P4} from "p4api"
const p4 = new P4({p4set: {P4PORT: "p4server:1666"}})

// Asynchro mode
p4.cmd(p4Cmd, input)
  .then(out => {
    // ...
  }
  .catch(err) {
    throw ("p4 not found");
  };

// Asynchro with async-await
try {
  let out = await p4.cmd(p4Cmd, input);
} catch (err) {
  throw ("p4 not found");
}


// Synchro mode
try {
  let out = p4.cmdSync(p4Cmd, input);
} catch (err) {
  throw ("p4 not found");
}

Where:

  • p4Cmd is the Perforce command (string) with options separated with space.
  • input is a optional string or object for input value (like password for login command or client object for client command).

p4.cmd() return a promise which is resolved with the marshalled result of the command as an object (out).
p4.cmdSync() return the marshal result of the command as an object (out).

out has the following structure:

  • prompt: string printed by perforce before the result (else empty string)
  • stat: if exists, list of all result with code=stat
  • info: if exists, list of all result with code=info
  • error: if exists, list of all result with code=error

Row syntax commands

rawCmd(p4Cmd, [input]) and rawCmdSync(p4Cmd, [input]) allow to execute any p4 command using text syntax. Arguments and result are similar to the last method except that the marshalled syntax is replaced with a raw text syntax. Both raw methods return result as the following structure:

  • text: success result string or empty string
  • error: error result string or empty string

Error handling

If p4 client can not be executed (perforce not installed, bad path variable, ...), cmd is rejected and cmdSync is throwed with a P4.Error Error instance.

When timeout is reached, cmd is rejected and cmdSync is throwed with a P4.TimeoutError Error instance with message like 'Timeout <timeout>ms reached'

import {P4} from "p4api";
let p4 = new P4({p4set: {{P4PORT: "p4server:1666", P4API_TIMEOUT: 5000}});

function P4Error(msg) {
  this.name = "p4 error";
  this.message = msg;
}

async function p4(cmd, input) {
  let out
  try {
    out = await p4.cmd(cmd, input)
  } catch (err) {
    if (err instanceof P4.TimeoutError) {
      // Time out error
      throw new Error("p4 timeout " + err.timeout + " ms");
    }
    if (err instanceof P4.Error) {
      // Time out error
      throw new Error("p4 execution error. Check perforce installation");
    }
    // Critical error : not expected
    throw new Error("I don't know what appends");
  }
  if (out.error !== undefined) {
    // p4 command error
    throw new P4Error(out.error);
  }
  return out;
}

Cancellation feature

A promise returned by p4.cmd() can be canceled with cancel() method, killing launched p4 process.

Examples

List of depots

import {P4} from "p4api";
let p4 = new P4({p4set: {{P4PORT: "p4server:1666"}});
    
p4.cmd("depots").then(function(out){console.log(out);});

Result is like:

    {
      "prompt": "",
      "stat": [
        {
          "code": "stat",
          "name": "CM",
          "time": "1314373478",
          "type": "local",
          "map": "/perforce/Data/CM/...",
          "desc": "Created by xxxx. ..."
        },
        {
          "code": "stat",
          "name": "depot",
          "time": "1314374519",
          "type": "local",
          "map": "/perforce/Data/depot/...",
          "desc": "Created by xxxx. ..."
        }
      ]
    }

Command Error

    ...
    p4.cmd("mistake")
    ...

Result is:

{
  "prompt": "",
  "error": [
    {
      "code": "error",
      "data": "Unknown command.  Try \"p4 help\" for info.\n",
      "severity": 3,
      "generic": 1
    }
  ]
}

Login (command with prompt and input)

    ...
    p4.cmd("login", "myGoodPasswd")
    ...

Result is like:

{
  "prompt": "Enter password: ↵",
  "info": [
    {
      "code": "info",
      "data": "Success:  Password verified.",
      "level": 5
    },
    {
      "code": "info",
      "data": "User toto logged in.",
      "level": 0
    }
  ]
}

Check Login (command with param)

    ...
    p4.cmd("login -s")
    ...

Result is like:

{
  "prompt": "",
  "stat": [
    {
      "code": "stat",
      "TicketExpiration": "85062",
      "user": "toto"
    }
  ]
}

Clear viewpathes of the current Client

async function clearViewPathes() {
  let out = await p4.cmd("client -o")
  let client = out.stat[0]
  for (let i = 0;; i++) {
    if (client["View" + i] === undefined) break
    delete client["View" + i]
  }
  await p4.cmd("client -i", client)
  await p4.cmd("sync -f")
}

Cancellation

let p4Promise = p4.cmd("clients");
...
let   result = null;
if (DoNotNeedResult) {
  p4Promise.cancel();
} else {
  result = await p4Promise;
}