@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 normalized 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 | null;

null when the handler addresses code directly and has no version to pin, e.g. a dev server

InstallOptions

type InstallOptions = object;

Properties

noConfirm?

optional noConfirm?: boolean;

skip the confirm prompt and report the install with a notice instead; the record stays scoped to the calling app

version?

optional version?: string;

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

MountedPackage

type MountedPackage<T> = PackageConnection<T> & object;

Type Declaration

frame

frame: HTMLIFrameElement;

the frame in YOUR document. Style it, move it, fullscreen it: the broker does not own it

unmount

unmount: () => void;

remove the frame and settle closed

Returns

void

Type Parameters

T

T = unknown

MountOptions

type MountOptions = AppConnectOptions & object;

Type Declaration

element

element: Element;

where the package’s frame goes; it is appended here and fills it

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;

normalized 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";

PackageView

type PackageView = object;

Properties

hide

hide: () => void;

release this view; equivalent to packages.hide(uri, { element })

Returns

void

refresh

refresh: () => void;

force a re-measure, e.g. right after a layout change the tracker cannot observe

Returns

void

PickOptions

type PickOptions = object;

Properties

multiple?

optional multiple?: boolean;

title?

optional title?: string;

untrusted, rendered as text in the picker header

Placement

type Placement = object;

Properties

clip?

optional clip?: SurfaceRect;

the part of rect still visible after the placeholder’s scroll ancestors clip it

radius?

optional radius?: Radii;

the placeholder’s corner radii, so the frame follows a rounded container

rect

rect: SurfaceRect;

where the package frame sits, so its own layout gets the full box

Radii

type Radii = [number, number, number, number];

corner radii in css order: top-left, top-right, bottom-right, bottom-left

RawPackageConnection

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

ShowOptions

type ShowOptions = object;

Properties

element?

optional element?: HTMLElement;

A placeholder the package frame is aligned to for as long as the view lives. The frame tracks its rect every animation frame, is clipped by its scrolling ancestors, and follows its border-radius, so it reads as inline content even though it renders in FKN’s overlay.

rect?

optional rect?: SurfaceRect;

an explicit viewport rect, for a caller that tracks placement itself

SurfaceRect

type SurfaceRect = object;

viewport coordinates, the space both the app and the broker frame measure in

Properties

height

height: number;

width

width: number;

x

x: number;

y

y: number;

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

hide()

function hide(uri, options?): Promise<void>;

Hide a package’s frame again, the counterpart to show(). Pass the same element to release only the view bound to it; with no element every view of this package is released. The connection is untouched, so the package can be shown again.

Parameters

uri

string

options?

ShowOptions = {}

Returns

Promise<void>

install()

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

Install a package for this app behind an FKN-rendered confirm, or with { noConfirm: true } for a notice instead of a prompt. Resolves null when the user declines.

Parameters

uri

string

options?

InstallOptions

Returns

Promise<InstalledPackage | null>

isVisible()

function isVisible(): boolean;

True while a host app is showing this package’s frame. Packages start hidden.

Returns

boolean

list()

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

The packages installed by this app.

Returns

Promise<InstalledPackage[]>

mount()

function mount<T>(uri, options): Promise<MountedPackage<T>>;

Mount a package’s frame in YOUR document and connect to it, instead of positioning a frame the broker owns and clipping the overlay to it the way show() does.

The frame is an ordinary element: it lays out, scrolls, stacks and fullscreens with the rest of your page, and there is no geometry to translate, which is what makes this work from an app that is itself embedded. The package still gets its own origin and its own broker connection.

Needs a package built against this version of the lib: an older one only accepts a port from fkn.app.

Type Parameters

T

T = unknown

Parameters

uri

string

options

MountOptions

Returns

Promise<MountedPackage<T>>

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

onVisibilityChange()

function onVisibilityChange(handler): object;

Observe whether a host app is showing this package’s frame, so it can render its UI only while on screen. The handler is called immediately with the current state, and on every change after.

Parameters

handler

(visible) => 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[]>

show()

function show(uri, options): Promise<PackageView>;

Show an installed, connected package’s frame over this page, aligned to element (or an explicit rect). The package renders its own UI there; the app keeps the space in its own layout. Take it back down with hide() on the returned view, or with packages.hide(uri). Throws a PackagesError with code ‘not-installed’ when the package has not been connected by this app.

Parameters

uri

string

options

ShowOptions

Returns

Promise<PackageView>

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>