Application Programming Interface (API)

Deprecated in Pear v2.6.5, removed as of Pear v3. The global.Pear direct-access API documented here was injected by the removed pear run command and is superseded by Pear OTA (the pear-runtime module)—instantiate Pear and use its API instead. This page is retained for reference.

Pear is built on Bare. Pear applications have a global.Pear object. For background on the runtime split, see Runtime and languages; for the surrounding pear-* library catalog, see Modules. For the global.Bare object, see the Bare runtime API.

`global.Pear`

The Pear Platform API is made available globally as Pear.

The Pear API is designed to be as minimal as possible.

The majority of capabilities are supplied via Pear Modules.

`Pear.app <Object>`

REMOVED—superseded by the Pear OTA (pear-runtime) API (instantiate Pear and use its instance instead). Applies to all Pear.app.* properties below.

Contains application information. Supersedes Pear.config.

`Pear.app.key <Buffer|null>`

REMOVED

A buffer of the application key. If running from disk, Pear.app.key is null.

`Pear.app.length <Integer>`

REMOVED

The application drive length. The application version consists of Pear.app.key, Pear.app.length and Pear.app.fork.

`Pear.app.fork <Integer>`

REMOVED

The application drive fork count. A fork is where the append-only log of the drive is truncated.

The application version consists of Pear.app.key, Pear.app.length and Pear.app.fork.

`Pear.app.alias <String|null>`

REMOVED

Given an application that is run from a pear:// link with an alias it, contains that alias. For example the Pear.app.alias for pear run pear://myapp would be myapp.

`Pear.app.dev <Boolean>`

REMOVED

Whether the application is in development mode.

Note that development mode means, the application has been run with the --dev flag.

Development mode is not the same as development environment. Development environment equates to running from disk.

For example, to detect both development mode & environment:

const fromDisk = Pear.app.key === null
const isDev = fromDisk && Pear.app.dev

`Pear.app.name <String>`

REMOVED

Application name.

`Pear.app.main <String>`

REMOVED

Application entry file.

`Pear.app.channel <String|null>`

REMOVED

Application release/staging channel.

`Pear.app.storage <String>`

REMOVED

Application storage path

`Pear.app.options <Object>`

REMOVED

Configuration options. The pear configuration object as supplied via an applications package.json file.

References

Configuration

`Pear.app.env <Object>`

REMOVED

The environment variables that an application was started with, as key-value pairs in an object.

`Pear.app.flags <Object>`

REMOVED

Parsed command-line flag values as supplied when an application was started.

`Pear.app.checkout <String>`

REMOVED

The value of the pear run --checkout flag. Same as Pear.app.flags.checkout.

References

pear run
Pear.app.flags

`Pear.app.storage <String>`

REMOVED

Application storage path.

`Pear.app.args <Array>`

REMOVED

Command-line application arguments passed like pear run --dev . --some arg.

`Pear.app.release <Number>`

REMOVED

The current release length as marked by the pear release command.

References

pear release

`Pear.app.link <String>`

REMOVED

The link that was passed to pear run with alias resolved to key.

Includes any potential pathname, query or fragment.

References

pear run

`Pear.app.links <Object|Array>`

REMOVED

Holds trusted Pear application links and domains as specified in the links field inside package.json.

References

`Pear.app.routes <String>`

REMOVED

The configuration provided pear.routes mapping object.

`Pear.app.entrypoint <String>`

REMOVED

The link pathname (pear://<key>/<pathname>), after any route mappings have been applied per pear.routes.

Includes the leading /, e.g given pear://foo/bar/baz, Pear.app.entrypoint would be /bar/baz.

Only Pear.app.entrypoint supports route-mapping via the pear.routes mapping object. Pear.app.route is provides access the raw pathname, including the leading slash (/), while Pear.app.linkData is legacy, excludes the slash, but is still supported.

Pear.app.route
Pear.app.routes
pear.routes

`Pear.app.fragment <String>`

REMOVED

The link hash, without the leading #.

Given pear://<key>/<pathname>#frag Pear.app.fragment would be frag.

`Pear.app.query <String>`

REMOVED

The link query string, without the leading ?.

Given pear://<key>/<pathname>?qs Pear.app.query would be qs.

`Pear.app.route <String>`

REMOVED

The link pathname (pear://<key>/<pathname>), prior to any route mappings being applied.

Includes the leading /, e.g given pear://foo/bar/baz, Pear.app.route would be /bar/baz.

References

Pear.app.entrypoint
Pear.app.routes
pear.routes

`Pear.app.linkData <String>`

REMOVED

Holds just the data portion of a Pear link.

The Pear link of an application. Takes the form pear://<key>/<data>.

In development, pear://dev/<data>.

Unlike Pear.app.route and Pear.app.entrypoint does not include the leading slash (/).

Legacy but still supported. Prefer Pear.app.entrypoint or Pear.app.route.

References

Pear.app.entrypoint
Pear.app.route
Pear.app.link
pear run

`Pear.app.checkpoint <Any>`

REMOVED

Holds state as set by Pear.checkpoint(). When an application restarts it will hold the most recent value passed to Pear.checkpoint().

Stores state that will be available as Pear.app.checkpoint next time the application starts.

The Pear.app.checkpoint property immediately reflects the latest checkpoint.

The returned Promise will resolve once the checkpoint has been successfully stored.

References

Pear.checkpoint()

`Pear.app.release <Integer>`

REMOVED

Application release sequence integer.

`Pear.app.flags <Object>`

REMOVED

Parsed pear run flags.

`Pear.app.applink <String>`

REMOVED

Pear application link. May be a pear:// link or a local directory.

`Pear.app.dir <String>`

REMOVED

The current working directory of pear run when the application was started.

`Pear.app.dht.nodes <Array<Object>>`

REMOVED

A list of known DHT nodes of the form { host: <String>, port: <Number> }. The nodes are set when the Pear application is started.

Unless started with a custom set of bootstrap nodes, Pear caches known nodes to speed up connecting to the swarm and to make it more resilient.

`Pear.app.dht.bootstrap <Array<Object>>`

REMOVED

A list of custom bootstrap nodes Pear is started with of the form { host: <String>, port: <Number> }.

`Pear.app.assets <String>`

REMOVED

Advanced / integration purposes.

Per pear-assets configuration assets are fetched and stored to disk. Use Pear.app.assets[namespace].path to get the path that given asset is stored to.

Takes the form { [namespace]: { link <String>, ns <String>, path <String>, name <String>, only <Array<String>>, bytes <Integer> } }. namespace is per the property name on the assets object. By convention, should be describe the asset type, for example: ui.

link - Configuration supplied pear://<fork>.<length>.<key>
ns - Namespace - same as the property name
path - The path that Pear stored the asset to on-disk
name - Configuration supplied name
only - Configuration supplied only array
bytes - The total bytes used by asset on-disk

Example:

{
  "ui": {
    "link": "pear://0.940.cktxzetiwt6un3ado5kgqedge6ya4nfazjckzq76zcapefwxakdy",
    "ns": "ui",
    "path": "/Users/xxx/Library/Application Support/pear/assets/0c82035d08c00ae4da2f307eb5d2c1fd",
    "name": "Pear Runtime",
    "only": [
      "/boot.bundle",
      "/by-arch/%HOST%",
      "/prebuilds/%HOST%"
    ],
    "bytes": 259158801
  }
}

`Pear.app.prerunning <Boolean>`

REMOVED

Whether the current application is a pre script.

`Pear.app.startId <String>`

REMOVED

Advanced. Integration purposes.

The application start identifier. Can be used to register a pear-ipc client to an applicaiton, with ipc.identify()

`Pear.app.swapDir <String>`

REMOVED

Advanced. Integration purposes.

The active swap directory with Pear platform directory.

`Pear.app.pearDir <String>`

REMOVED

Advanced. Integration purposes.

Pear platform directory.

`Pear.checkpoint(<Any>) => Promise`

REMOVED

Stores state that will be available as Pear.app.checkpoint next time the application starts.

The Pear.app.checkpoint property immediately reflects the latest checkpoint.

The returned Promise will resolve once the checkpoint has been successfully stored.

References

Pear.app.checkpoint

`Pear.teardown(fn <Async Function|Function>)`

REMOVED

May be called multiple times to register multiple teardown handlers.

Functions supplied to teardown will be executed in order of registration when an application begins to unload. Any promise returned from each supplied function will be waited upon until resolution before calling the next teardown handler.

`Pear.argv`

REMOVED—use Bare.argv.

The command line arguments passed to the process when launched.

`Pear.pid`

REMOVED—use Bare.pid.

The ID of the current process.

`Pear.exitCode`

REMOVED—use Bare.exitCode.

The code that will be returned once the process exits. If the process is exited using Bare.exit() without specifying a code, Bare.exitCode is used.

`Pear.exit(code)`

REMOVED—use Bare.exit().

Exits the process with the provided exit code. Follows Pear teardown flow, whereas Bare.exit() does not.

`Pear.constructor.CUTOVER` (Integration)

REMOVED

Integration APIs may change.

For auto-cutover opt-out do Pear.constructor.CUTOVER = false in the first-tick.

Cutover signals the end of the application init phase and instructs sidecar to stop buffering critical streams, such as updates.

This stops an internal ipc.cutover call to the sidecar, indicating that a manual call will be made later which in turn allows child processes to listen to critical streams without any data loss but the onus is then on child process to call cutover in order free resources in the sidecar.

`Pear.constructor.COMPAT` (Integration)

REMOVED

Integration APIs may change.

Compat-mode opt-in for legacy applications. For JavaScript projects, use the pear-runtime reference.

`Pear.constructor.RTI` (Integration)

REMOVED

Integration APIs may change.

Runtime Information. Used by additional runtimes to bootstrap runtime state at boot. Used by pear-run.

`Pear.constructor.IPC` (Integration)

REMOVED

Integration APIs may change.

Symbol for accessing built-in IPC client. Used by libraries and other integrations.

const ipc = Pear[Pear.constructor.IPC]

`Pear.constructor.RUNTIME` (Integration)

REMOVED

Integration APIs may change.

The runtime binary to spawn when running. Used by pear-run. Useful for certain testing scenarios.

`Pear.constructor.RUNTIME_ARGV` (Integration)

REMOVED

Integration APIs may change.

Used to modify argv passed spawn when running. Used by pear-run. Useful for certain testing scenarios.

Example:

{
  platform: {
    key: 'pzcjqmpoo6szkoc4bpkw65ib9ctnrq7b6mneeinbhbheihaq6p6o',
    length: 5949,
    fork: 0
  },
  app: { key: null, length: 0, fork: 0 },
  runtimes: { bare: '1.24.3', pear: '2.2.6' }
}

Application Programming Interface (API)

On this page