API

Pear is built on Bare. Pear applications have a global.Pear object and aglobal.Bare object.

global.Pear

stable

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>

Contains application information. Supersedes Pear.config.

Pear.app.key <Buffer|null>

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

Pear.app.length <Integer>

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

Pear.app.fork <Integer>

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>

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://keet would be keet.

Pear.app.dev <Boolean>

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:

Pear.app.name <String>

Application name.

Pear.app.main <String>

Application entry file.

Pear.app.channel <String|null>

Application release/staging channel.

Pear.app.storage <String>

Application storage path

Pear.app.options <Object>

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

References

Pear.app.env <Object>

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

Pear.app.flags <Object>

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

Pear.app.checkout <String>

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

References

Pear.app.storage <String>

Application storage path.

Pear.app.args <Array>

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

Pear.app.release <Number>

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

References

Pear.app.link <String>

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

Includes any potential pathname, query or fragment.

References

Pear.app.links <Object|Array>

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

References

Pear.app.routes <String>

The configuration provided pear.routes mapping object.

Pear.app.entrypoint <String>

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.fragment <String>

The link hash, without the leading #.

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

Pear.app.query <String>

The link query string, without the leading ?.

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

Pear.app.route <String>

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.linkData <String>

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.checkpoint <Any>

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.app.release <Integer>

Application release sequence integer.

Pear.app.flags <Object>

Parsed pear run flags.

Pear.app.applink <String>

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

Pear.app.dir <String>

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

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

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>>

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

Pear.app.assets <String>

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:

Pear.app.prerunning <Boolean>

Whether the current application is a pre script.

Pear.app.startId <String>

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>

Advanced. Integration purposes.

The active swap directory with Pear platform directory.

Pear.app.pearDir <String>

Advanced. Integration purposes.

Pear platform directory.

Pear.checkpoint(<Any>) => Promise

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.teardown(fn <Async Function|Function>)

Register application clean-up handlers to be called when an application begins to unload.

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

The command line arguments passed to the process when launched.

Pear.pid

The ID of the current process.

Pear.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)

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

Pear.constructor.CUTOVER (Integration)

NOTE: 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)

NOTE: Integration APIs may change.

Compat-mode opt-in. See [./migration.md#compat-mode]

Pear.constructor.RTI (Integration)

NOTE: Integration APIs may change.

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

Pear.constructor.IPC (Integration)

NOTE: Integration APIs may change.

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

Pear.constructor.RUNTIME (Integration)

NOTE: 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)

NOTE: Integration APIs may change.

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

DEPRECATED Pear.restart()

Deprecated. Use pear-restart.

DEPRECATED Pear.config <Object>

Deprecated. Use Pear.app.

DEPRECATED Pear.messages([ pattern ], [ listener ]) -> Iterable

Deprecated. Use pear-messages.

DEPRECATED await Pear.message(<Object>)

Deprecated. Use pear-message.

DEPRECATED Pear.worker <Object>

Deprecated. Use pear-run & pear-pipe.

Deprecated. Use pear-pipe.

DEPRECATED Pear.media <Object>

Deprecated. Use pear-electron ui.media.

DEPRECATED Pear.versions <Async Function>

Outputs version information.

Example:

DEPRECATED Pear.reload()

Deprecated. Use location.reload() in Desktop apps. No reload in terminal apps.

DEPRECATED Pear.updates(listener <Async Function|Function>) =>streamx.Readable

Deprecated. Use pear-updates.

DEPRECATED const update = await Pear.updated()

Deprecated. No-op. Do not use.

DEPRECATED Pear.wakeups(listener <Async Function|Function>) =>streamx.Readable

Deprecated. Use pear-updates.

DEPRECATED Pear.badge(count <Integer|null>) =>Promise<Boolean>

Deprecated. Use pear-electron ui.app.badge().

DEPRECATED Pear.tray(options <Object>, listener <AsyncFunction|Function>) => Promise<untray()>

Deprecated. Use pear-electron ui.app.tray().

DEPRECATED const win = new Pear.Window(entry <String>, options<Object>)

Deprecated. Use pear-electron ui.Window.

DEPRECATED const view = new Pear.View(options <Object>)

Deprecated. Use pear-electron ui.View.

global.Bare

stable

The core JavaScript API of Bare is available through the global Bare namespace.

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

The majority of capabilities are supplied via Bare Modules.

Bare.platform

The identifier of the operating system for which Bare was compiled. The possible values are android, darwin, ios, linux, and win32.

Bare.arch

The identifier of the processor architecture for which Bare was compiled. The possible values are arm, arm64, ia32, mips, mipsel, and x64.

Bare.simulator

Whether or not Bare was compiled for a simulator.

Bare.argv

The command line arguments passed to the process when launched.

Bare.pid

The ID of the current process.

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.

Bare.suspended

Whether or not the process is currently suspended.

Bare.exiting

Whether or not the process is currently exiting.

Bare.version

The Bare version string.

Bare.versions

An object containing the version strings of Bare and its dependencies.

Bare.exit([code])

Immediately terminate the process or current thread with an exit status of code which defaults to Bare.exitCode.

Bare.suspend([linger])

Suspend the process and all threads. This will emit a suspend event signalling that all work should stop immediately. When all work has stopped and the process would otherwise exit, an idle event will be emitted. If the process is not resumed from an idle event listener, the loop will block until the process is resumed.

Bare.idle()

Immediately suspend the event loop and trigger the idle event.

Bare.resume()

Resume the process and all threads after suspension. This can be used to cancel suspension after the suspend event has been emitted and up until all idle event listeners have run.

Bare.on('uncaughtException', err)

Emitted when a JavaScript exception is thrown within an execution context without being caught by any exception handlers within that execution context. By default, uncaught exceptions are printed to stderr and the processes aborted. Adding an event listener for the uncaughtException event overrides the default behavior.

Bare.on('unhandledRejection', reason, promise)

Emitted when a JavaScript promise is rejected within an execution context without that rejection being handled within that execution context. By default, unhandled rejections are printed to stderr and the process aborted. Adding an event listener for the unhandledRejection event overrides the default behavior.

Bare.on('beforeExit', code)

Emitted when the loop runs out of work and before the process or current thread exits. This provides a chance to schedule additional work and keep the process from exiting. If additional work is scheduled, beforeExit will be emitted again once the loop runs out of work.

If the process is exited explicitly, such as by calling Bare.exit() or as the result of an uncaught exception, the beforeExit event will not be emitted.

Bare.on('exit', code)

Emitted when the process or current thread exits. If the process is forcefully terminated from an exit event listener, the remaining listeners will not run.

[!CAUTION] Additional work MUST NOT be scheduled from an exit event listener.

Bare.on('suspend', linger)

Emitted when the process or current thread is suspended. Any in-progress or outstanding work, such as network activity or file system access, should be deferred, cancelled, or paused when the suspend event is emitted and no additional work should be scheduled.

Bare.on('idle')

Emitted when the process or current thread becomes idle after suspension. After all handlers have run, the event loop will block and no additional work be performed until the process is resumed. An idle event listener may call Bare.resume() to cancel the suspension.

Bare.on('resume')

Emitted when the process or current thread resumes after suspension. Deferred and paused work should be continued when the resume event is emitted and new work may again be scheduled.

Bare.Addon

The Bare.Addon namespace provides support for loading native addons, which are typically written in C/C++ and distributed as shared libraries.

const addon = Addon.load(url[, options])

Load a static or dynamic native addon identified by url. If url is not a static native addon, Bare will instead look for a matching dynamic object library.

Options are reserved.

const unloaded = Addon.unload(url[, options])

Unload a dynamic native addon identified by url. If the function returns true, the addon was unloaded from memory. If it instead returns false, the addon is still in use by one or more threads and will only be unloaded from memory when those threads either exit or explicitly unload the addon.

Options are reserved.

const url = Addon.resolve(specifier, parentURL[, options])

Resolve a native addon specifier by searching for a static native addon or dynamic object library matching specifier imported from parentURL.

Options are reserved.

Bare.Thread

The Bare.Thread provides support for lightweight threads. Threads are similar to workers in Node.js, but provide only minimal API surface for creating and joining threads.

Thread.isMainThread

true if the current thread is the main thread.

Thread.self

A reference to the current thread as a ThreadProxy object. Will be null on the main thread.

Thread.self.data

A copy of or, if shared, reference to the data buffer that was passed to the current thread on creation. Will be null if no buffer was passed.

const thread = new Thread([filename][, options][, callback])

Start a new thread that will run the contents of filename. If callback is provided, its function body will be treated as the contents of filename and invoked on the new thread with Thread.self.data passed as an argument.

Options include:

const thread = Thread.create([filename][, options][, callback])

Convenience method for the new Thread() constructor.

thread.joined

Whether or not the thread has been joined with the current thread.

thread.join()

Block and wait for the thread to exit.

thread.suspend([linger])

Suspend the thread. Equivalent to calling Bare.suspend() from within the thread.

thread.resume()

Resume the thread. Equivalent to calling Bare.resume() from within the thread.

Last updated