@fkn/lib/packages

Type Aliases

AppConnectOptions

type AppConnectOptions = ConnectOptions & object;

Type Declaration

payload?

optional payload?: unknown;

exposed to the package as ITS remote

raw?

optional raw?: boolean;

skip the osra handshake and hand back the untouched port - e.g. to transfer it into a worker and attach() there

signal?

optional signal?: AbortSignal;

Connect

type Connect = {
<T>  (uri, options?): Promise<PackageConnection<T>>;
  (uri, options): Promise<RawPackageConnection>;
};

Call Signature

<T>(uri, options?): Promise<PackageConnection<T>>;

Type Parameters

T

T = unknown

Parameters

uri

string

options?

ConnectOptions & object & object

Returns

Promise<PackageConnection<T>>

Call Signature

(uri, options): Promise<RawPackageConnection>;

Parameters

uri

string

options

ConnectOptions & object & object

Returns

Promise<RawPackageConnection>

ConnectOptions

type ConnectOptions = object;

Properties

protocol?

optional protocol?: string;

opaque contract tag delivered to the package’s onConnect, e.g. ‘stub-source@1’

ConnectPayload

type ConnectPayload = (info) => unknown;

produces the payload exposed to a connecting app - called once per incoming connection

Parameters

info

IncomingConnectionInfo

Returns

unknown

IncomingConnection

type IncomingConnection<T> = IncomingConnectionInfo & PackageConnection<T>;

Type Parameters

T

T = unknown

IncomingConnectionInfo

type IncomingConnectionInfo = object;

Properties

from

from: string;

the connecting app’s identity: its package uri when it runs on a sandbox origin, else its page origin

name

name: string;

this package’s npm name

protocol

protocol: string | null;

the contract tag the app passed to connect(), e.g. ‘stub-source@1’

uri

uri: string;

this package’s canonical uri per the connecting app’s install record, e.g. ‘npm:@banou/stub-source-example’

version

version: string;

the exact version this frame runs - the pin is encoded into the sandbox origin, immutable per version

InstalledPackage

type InstalledPackage = object;

Properties

installedAt

installedAt: number;

name

name: string;

uri

uri: string;

version

version: string;

InstallOptions

type InstallOptions = object;

Properties

version?

optional version?: string;

exact version to pin; defaults to the packument’s latest dist-tag

PackageConnection

type PackageConnection<T> = object;

Type Parameters

T

T = unknown

Properties

closed

closed: Promise<void>;

settles when the package side of the connection dies (uninstall, reload, crash) - reconnect by calling connect() again

port

port: MessagePort;

the raw channel under remote, for direct messaging (osra envelopes ride it too - filter by your own message shape)

remote

remote: Remote<T>;

the package’s exposed payload

PackageQuery

type PackageQuery = object;

Properties

id?

optional id?: string;

host app scope, e.g. ‘stub’ - becomes the keyword fkn-<type>--<id>

origin?

optional origin?: "npm";

package source; npm is the only origin implemented

size?

optional size?: number;

result count, clamped to 1..100

text?

optional text?: string;

free text mixed into the registry query

type

type: string;

package kind, e.g. ‘plugin’ - becomes the keyword fkn-type:<type>

PackageResult

type PackageResult = object;

Properties

description

description: string;

downloadsMonthly

downloadsMonthly: number | null;

installed

installed: boolean;

installed by the calling app

keywords

keywords: string[];

links

links: object;

homepage?

optional homepage?: string;

npm?

optional npm?: string;

repository?

optional repository?: string;

name

name: string;

origin

origin: "npm";

publisher

publisher: string | null;

uri

uri: string;

canonical version-free uri, e.g. ‘npm:@banou/stub-plugin-foo’

version

version: string;

latest version per the search index - display only, install re-resolves from the packument

PackagesError

type PackagesError = Error & object;

Type Declaration

code

code: PackagesErrorCode;

PackagesErrorCode

type PackagesErrorCode =
  | "invalid"
  | "not-installed"
  | "unaddressable"
  | "timeout"
  | "unavailable"
  | "denied";

PickOptions

type PickOptions = object;

Properties

multiple?

optional multiple?: boolean;

title?

optional title?: string;

untrusted, rendered as text in the picker header

RawPackageConnection

type RawPackageConnection = Omit<PackageConnection<never>, "remote">;

Variables

connect

const connect: Connect;

Connect to an installed package. Throws a PackagesError with code ‘not-installed’ when it is not.

Functions

attach()

function attach<T>(
   port,
   payload?,
options?): Promise<Remote<T>>;

Run this end of an already-brokered connection port, e.g. after transferring it into a worker.

Type Parameters

T

T = unknown

Parameters

port

MessagePort

payload?

unknown

options?

signal?

AbortSignal

Returns

Promise<Remote<T>>

install()

function install(uri, options?): Promise<InstalledPackage | null>;

Install a package for this app behind an FKN-rendered confirm. Resolves null when the user declines.

Parameters

uri

string

options?

InstallOptions

Returns

Promise<InstalledPackage | null>

list()

function list(): Promise<InstalledPackage[]>;

The packages installed by this app.

Returns

Promise<InstalledPackage[]>

onConnect()

function onConnect<T>(createPayload, handler?): object;

Serve connections from apps that installed this package. The first argument is called once per incoming connection with the connection info and returns the payload exposed to that app (its remote). The latest registration receives new connections; existing connections are unaffected.

Type Parameters

T

T = unknown

Parameters

createPayload

ConnectPayload

handler?

(connection) => void

Returns

object

unsubscribe

unsubscribe: () => void;

Returns

void

pick()

function pick(query, options?): Promise<PackageResult[]>;

FKN-rendered picker over the same search; resolves the user’s selection, already installed. [] on cancel.

Parameters

search()

function search(query): Promise<PackageResult[]>;

Search npm for FKN packages, e.g. search({ type: 'plugin', id: 'stub' }).

Parameters

query

PackageQuery

Returns

Promise<PackageResult[]>

uninstall()

function uninstall(uri): Promise<void>;

Uninstall a package from this app; its frames and connections are torn down.

Parameters

uri

string

Returns

Promise<void>