@tokamakdev/plugin 0.1.0-beta.126 → 0.1.0-beta.128

package/README.md

@@ -24,8 +24,9 @@ export function alarms(ctx: TokamakContext) { return new Alarms(ctx); }
 ```
 
 `call` uses the standard JSON endpoint codec. `callBytes` sends and receives
-opaque bytes. `stream` exposes JSON values as a cancellable byte stream;
-`decodeValues<T>` consumes it. Errors terminate a stream. A slow consumer
+opaque bytes. `stream` exposes JSON values as a cancellable byte stream,
+subscribing once a promised argument resolves; `decodeValues<T>` consumes it.
+Errors, including that promise's rejection, terminate a stream. A slow consumer
 exceeding its bounded buffer receives `QuotaExceededError`.
 
 Declare the factory in `tokamak-plugin.json` alongside native build metadata:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin",
-  "version": "0.1.0-beta.126",
+  "version": "0.1.0-beta.128",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -10,7 +10,6 @@
   "exports": {
     ".": "./src/index.ts",
     "./streams": "./src/streams.ts",
-    "./bindings": "./src/bindings.ts",
     "./events": "./src/events.ts",
     "./worker": "./src/worker.ts",
     "./testing": "./src/testing.ts",

package/src/index.ts

@@ -55,17 +55,21 @@ export abstract class Plugin {
   }
 
   /**
-   * A stream of newline-delimited JSON values, consumed with decodeValues. `overflow` says what
-   * happens to values a slow reader has not taken: ending the stream, or dropping the oldest.
+   * A stream of newline-delimited JSON values, consumed with decodeValues. A promised `value`
+   * subscribes once it resolves, and its rejection ends the stream. `overflow` says what happens
+   * to values a slow reader has not taken: ending the stream, or dropping the oldest.
    */
   protected stream<T>(method: string, value: unknown = null, overflow: Overflow = "error"): JsonStream<T> {
-    return byteStream((next, error, close) => this.ctx[nativeConnection].listen(this.pluginId, method, encodeJson(value), {
-      next(payload, done) {
-        next(jsonLine(payload));
-        if (done) close();
-      },
-      error,
-      overflow,
-    }), overflow);
+    return byteStream((next, error, close) => {
+      const listen = (argument: unknown) => this.ctx[nativeConnection].listen(this.pluginId, method, encodeJson(argument), {
+        next(payload, done) {
+          next(jsonLine(payload));
+          if (done) close();
+        },
+        error,
+        overflow,
+      });
+      return value instanceof Promise ? value.then(listen) : listen(value);
+    }, overflow);
   }
 }

package/src/resources.ts

@@ -6,9 +6,6 @@ const collected = typeof FinalizationRegistry === "function"
   ? new FinalizationRegistry<() => void>((release) => { release(); })
   : undefined;
 
-/** The invocation that owns `reference`. */
-export let ownerOf: (reference: NativeReference) => TokamakContext;
-
 /**
  * A native object that stays in native memory. The receiving invocation owns it until `close`,
  * the invocation's end, or garbage collection where the runtime has `FinalizationRegistry`.
@@ -18,10 +15,6 @@ export class NativeReference {
   readonly #id: string;
   #release: (() => void) | undefined;
 
-  static {
-    ownerOf = (reference) => reference.#ctx;
-  }
-
   private constructor(ctx: TokamakContext, id: string, release: () => void) {
     this.#ctx = ctx;
     this.#id = id;
@@ -31,15 +24,9 @@ export class NativeReference {
 
   /**
    * Retains the object that the native subscription `method` of `plugin` holds open: its first
-   * value is the object's ID, and later values go to `next`.
+   * value is the object's ID.
    */
-  static async acquire(
-    ctx: TokamakContext,
-    plugin: string,
-    method: string,
-    payload: Uint8Array,
-    next: (value: Uint8Array) => void = () => {},
-  ): Promise<NativeReference> {
+  static async acquire(ctx: TokamakContext, plugin: string, method: string, payload: Uint8Array): Promise<NativeReference> {
     let release = () => {};
     try {
       // The subscription's listeners never hold the reference, so garbage collection can release it.
@@ -47,10 +34,7 @@ export class NativeReference {
         let settled = false;
         release = ctx[nativeConnection].listen(plugin, method, payload, {
           next(value, done) {
-            if (settled) {
-              if (!done) next(value);
-              return;
-            }
+            if (settled) return;
             settled = true;
             if (done) reject(new DOMException("The native object was not retained", "InvalidStateError"));
             else resolve(value);
@@ -70,14 +54,6 @@ export class NativeReference {
     }
   }
 
-  /** The object retained as `id` in the scope of the invocation `ctx`, which ends with it. */
-  static scoped(ctx: TokamakContext, id: string): NativeReference {
-    return new NativeReference(ctx, id, () => {
-      // A failed release changes nothing: the invocation's end has released the object.
-      ctx[nativeConnection].call("tokamak", "resource.release", encodeJson(id)).catch(() => undefined);
-    });
-  }
-
   /** Copies the current contents of a native byte buffer. Other native objects reject with `TypeError`. */
   async bytes(): Promise<Uint8Array> {
     return this.#ctx[nativeConnection].call("tokamak", "resource.read", encodeJson(this.idFor(this.#ctx)));

package/src/bindings.ts

@@ -1,246 +0,0 @@
-import { nativeConnection, type TokamakContext } from "./context.js";
-import { decodeJson, encodeJson } from "./codec.js";
-import { nativeError, type NativeFailure } from "./native-protocol.mjs";
-import { NativeReference, ownerOf } from "./resources.js";
-import { byteStream } from "./streams.js";
-
-export type { TokamakContext } from "./context.js";
-export { NativeReference } from "./resources.js";
-
-/** The reference `object` views: pass it to another class's constructor or to a plugin's native endpoint. */
-export let referenceOf: (object: NativeObject) => NativeReference;
-
-/**
- * A native object that a generated binding returned. Its class mirrors the native class; every
- * member is asynchronous. The invocation that received it owns it until `release`, the
- * invocation's end, or garbage collection.
- */
-export class NativeObject {
-  readonly #reference: NativeReference;
-
-  static {
-    referenceOf = (object) => object.#reference;
-  }
-
-  /** Views the object `reference` holds as this class. The native side checks the type at each call. */
-  constructor(reference: NativeReference) {
-    this.#reference = reference;
-  }
-}
-
-/** Releases `object` for every view of it. Later calls on it reject with `InvalidStateError`. */
-export function release(object: NativeObject): void {
-  referenceOf(object).close();
-}
-
-type NativeClass = new (reference: NativeReference) => NativeObject;
-
-/** The classes of a binding module, by native name. */
-export type Classes = Readonly<Record<string, NativeClass>>;
-
-/** The calls of one generated binding module, whose native plugin is `plugin`. */
-export class Bindings {
-  readonly #plugin: string;
-  readonly #classes: () => Classes;
-
-  /** `classes` returns the module's classes once they are defined. */
-  constructor(plugin: string, classes: () => Classes) {
-    this.#plugin = plugin;
-    this.#classes = classes;
-  }
-
-  /**
-   * Calls `member` of `target`, the object or, for a static member, the invocation's context.
-   * Aborting `signal` cancels an asynchronous member's task.
-   */
-  async call<T>(target: TokamakContext | NativeObject, member: string, args: readonly unknown[], signal?: AbortSignal): Promise<T> {
-    const ctx = contextOf(target);
-    const reply = await ctx[nativeConnection].call(this.#plugin, member, await request(ctx, target, args), { signal });
-    return this.#decode(ctx, reply) as T;
-  }
-
-  /**
-   * The key of the first of `overloads` whose parameters take `args`: each parameter lists the
-   * kinds of value it takes, a class or a `typeof` name, `"array"`, `"bytes"`, `"date"`, `"object"`
-   * (a plain object), `"null"` or `"any"`.
-   */
-  overload(args: readonly unknown[], overloads: readonly (readonly [string, readonly (readonly Kind[])[]])[]): string {
-    const found = overloads.find(([, params]) =>
-      params.length === args.length && params.every((kinds, index) => kinds.some((kind) => takes(kind, args[index]))));
-    if (!found) throw new TypeError("No overload takes these arguments");
-    return found[0];
-  }
-
-  /** The elements of the native sequence `member` of `target` returns. Cancelling the stream ends it. */
-  stream<T>(target: TokamakContext | NativeObject, member: string, args: readonly unknown[]): ReadableStream<T> {
-    const ctx = contextOf(target);
-    const elements = byteStream(async (next, error, close) =>
-      ctx[nativeConnection].listen(this.#plugin, member, await request(ctx, target, args), {
-        next: (value, done) => { if (done) close(); else next(value); },
-        error,
-      }));
-    return elements.pipeThrough(new TransformStream<Uint8Array, T>({
-      transform: (element, controller) => { controller.enqueue(this.#decode(ctx, element) as T); },
-    }));
-  }
-
-  /**
-   * A native object implementing `protocol` whose `methods`, where `handlers` has them, call
-   * `handlers` in order. Its platform defaults remain for the methods `handlers` lacks.
-   */
-  async implement<T extends NativeObject>(
-    ctx: TokamakContext,
-    Protocol: new (reference: NativeReference) => T,
-    protocol: string,
-    methods: readonly string[],
-    handlers: object,
-  ): Promise<T> {
-    const handled = methods.filter((method) => typeof Reflect.get(handlers, method) === "function");
-    const payload = encodeJson({ scope: await scopeOf(ctx), methods: handled });
-    const reference = await NativeReference.acquire(ctx, this.#plugin, protocol, payload, (value) => {
-      const { method, arguments: args } = decodeJson<{ method: string; arguments: Wire[] }>(value);
-      const classes = this.#classes();
-      const handler = Reflect.get(handlers, method) as (...values: unknown[]) => unknown;
-      // The constructor runs the handler now, and rejects with what it throws.
-      new Promise((resolve) => { resolve(handler.apply(handlers, args.map((arg) => fromWire(arg, ctx, classes)))); })
-        .catch((error: unknown) => { reportError(error); });
-    });
-    return new Protocol(reference);
-  }
-
-  #decode(ctx: TokamakContext, payload: Uint8Array): unknown {
-    return fromWire(decodeJson<Wire>(payload), ctx, this.#classes());
-  }
-}
-
-/** A kind of value an overload's parameter takes. */
-type Kind = string | (abstract new (reference: NativeReference) => NativeObject);
-
-/** The kinds named by strings other than `typeof` results. */
-const named = new Map<string, (value: unknown) => boolean>([
-  ["any", () => true],
-  ["null", (value) => value === null || value === undefined],
-  ["array", (value) => Array.isArray(value)],
-  ["bytes", (value) => value instanceof Uint8Array],
-  ["date", (value) => value instanceof Date],
-  ["object", (value) => typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof NativeObject)],
-]);
-
-function takes(kind: Kind, value: unknown): boolean {
-  if (typeof kind === "function") return value instanceof kind;
-  const takes = named.get(kind);
-  return takes ? takes(value) : typeof value === kind;
-}
-
-/** The Android application `Context`. */
-export function applicationContext(ctx: TokamakContext): Promise<NativeReference> {
-  return root(ctx, "context");
-}
-
-/** The Android activity the app shows. Rejects with `NeedsUIError` while the app cannot show UI. */
-export function foregroundActivity(ctx: TokamakContext): Promise<NativeReference> {
-  return root(ctx, "activity");
-}
-
-/**
- * The Apple object a native screen is presented from: the top `UIViewController` on iOS, the
- * `NSWindow` on macOS. Rejects with `NeedsUIError` while the app cannot show UI.
- */
-export function presenter(ctx: TokamakContext): Promise<NativeReference> {
-  return root(ctx, "presenter");
-}
-
-async function root(ctx: TokamakContext, name: string): Promise<NativeReference> {
-  const payload = encodeJson({ scope: await scopeOf(ctx), name });
-  const id = decodeJson<string>(await ctx[nativeConnection].call("tokamak", "resource.root", payload));
-  return NativeReference.scoped(ctx, id);
-}
-
-const scopes = new WeakMap<TokamakContext, Promise<string>>();
-
-/** The scope that keeps the objects the invocation `ctx` receives until it ends. */
-function scopeOf(ctx: TokamakContext): Promise<string> {
-  let scope = scopes.get(ctx);
-  if (!scope) {
-    // The subscription stays open for the invocation, whose end releases the scope's objects.
-    scope = new Promise((resolve, reject) => {
-      ctx[nativeConnection].listen("tokamak", "resource.scope", encodeJson(null), {
-        next: (value) => { resolve(decodeJson<string>(value)); },
-        error: reject,
-      });
-    });
-    scopes.set(ctx, scope);
-  }
-  return scope;
-}
-
-function contextOf(target: TokamakContext | NativeObject): TokamakContext {
-  return target instanceof NativeObject ? ownerOf(referenceOf(target)) : target;
-}
-
-async function request(ctx: TokamakContext, target: TokamakContext | NativeObject, args: readonly unknown[]): Promise<Uint8Array> {
-  return encodeJson({
-    scope: await scopeOf(ctx),
-    target: target instanceof NativeObject ? toWire(target, ctx) : undefined,
-    arguments: args.map((arg) => toWire(arg, ctx)),
-  });
-}
-
-/**
- * Binding values as JSON. Objects tagged `#` carry what JSON lacks: native objects, dates, bytes,
- * errors, non-finite numbers, and records whose own keys include `#`.
- */
-type Wire = null | boolean | number | string | Wire[] | { [key: string]: Wire };
-
-function toWire(value: unknown, ctx: TokamakContext): Wire {
-  if (value === null || value === undefined) return null;
-  if (typeof value === "number" && !Number.isFinite(value)) return { "#": "number", value: String(value) };
-  if (typeof value !== "object") return value as Wire;
-  return objectToWire(value, ctx);
-}
-
-function objectToWire(value: object, ctx: TokamakContext): Wire {
-  const reference = value instanceof NativeObject ? referenceOf(value) : value;
-  if (reference instanceof NativeReference) return { "#": "object", id: reference.idFor(ctx) };
-  if (value instanceof Date) return { "#": "date", value: value.getTime() };
-  if (value instanceof Uint8Array) return { "#": "bytes", value: toBase64(value) };
-  if (Array.isArray(value)) return value.map((item) => toWire(item, ctx));
-  const fields = Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toWire(item, ctx)]));
-  return "#" in fields ? { "#": "record", value: fields } : fields;
-}
-
-type Tagged = Record<string, Wire>;
-
-/** The decoder of each tag. */
-const tags = new Map<string, (value: Tagged, ctx: TokamakContext, classes: Classes) => unknown>([
-  ["object", (value, ctx, classes) => {
-    const Class = (value.types as string[]).map((type) => classes[type]).find(Boolean) ?? NativeObject;
-    return new Class(NativeReference.scoped(ctx, value.id as string));
-  }],
-  ["number", (value) => Number(value.value)],
-  ["date", (value) => new Date(value.value as number)],
-  ["bytes", (value) => fromBase64(value.value as string)],
-  ["error", (value) => nativeError(value as unknown as NativeFailure)],
-  ["record", (value, ctx, classes) => fields(value.value as Tagged, ctx, classes)],
-]);
-
-function fromWire(value: Wire, ctx: TokamakContext, classes: Classes): unknown {
-  if (Array.isArray(value)) return value.map((item) => fromWire(item, ctx, classes));
-  if (value === null || typeof value !== "object") return value;
-  const decode = typeof value["#"] === "string" ? tags.get(value["#"]) : undefined;
-  return decode ? decode(value, ctx, classes) : fields(value, ctx, classes);
-}
-
-function fields(value: Record<string, Wire>, ctx: TokamakContext, classes: Classes): Record<string, unknown> {
-  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, fromWire(item, ctx, classes)]));
-}
-
-function toBase64(bytes: Uint8Array): string {
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary);
-}
-
-function fromBase64(text: string): Uint8Array {
-  return Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
-}