nervur 0.15.0 → 0.17.0

package/dist/being/silence.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// Silence is one distinguished value. Null is an answer. Silence is no answer.
+//
+// The ward's words are the other distinguished values: what her ward tells
+// her when no object came back and it knows why. Each is one frozen object
+// under one symbol key, so a being cannot make one by accident, none of them
+// crosses an edge as a value, and a being who compares against them needs
+// no fourth shape. `unreached` is one of them.
+import { WORD_KEY } from './types.js';
+export const silence = Symbol.for('quo.silence');
+export const isSilence = (x) => x === silence;
+// The words a door says to a key it has bound, and no other. They ride on
+// the wire as `{ quo: word }`, so a reply is checked against this list.
+export const DOOR_WORDS = ['removed', 'absent', 'unannounced', 'repeated', 'threw'];
+export const isDoorWord = (s) => typeof s === 'string' && DOOR_WORDS.includes(s);
+const WORDS = new Map();
+export const word = (name) => {
+    let w = WORDS.get(name);
+    if (!w)
+        WORDS.set(name, (w = Object.freeze({ [WORD_KEY]: name })));
+    return w;
+};
+export const isWord = (x) => x !== null && typeof x === 'object' && typeof x[WORD_KEY] === 'string';
+export const wordOf = (x) => x[WORD_KEY];
+// What came back is an answer and not one of the two things that are not
+// answers. A being who only wants the object writes one test instead of
+// three, and the three shapes stay three shapes: silence is no answer, a word
+// is her ward telling her why there is none.
+export const answered = (x) => !isSilence(x) && !isWord(x);
+// What she was told, with a word given its name and everything else left
+// exactly as it came. One value to compare against, so asking which word came
+// back is one test and not two joined by an and: `told(out) === 'late'` says
+// what `isWord(out) && wordOf(out) === 'late'` says, and says which answer
+// arrived instead when it is wrong, where the pair collapses to false and
+// names nothing. Silence stays the symbol it is, and an object stays itself.
+export const told = (x) => (isWord(x) ? wordOf(x) : x);
+// Unreached: no far door was reached. Nothing is known to have been
+// delivered, so asking again is safe. A being cannot produce it: a ward that
+// sees a word come out of a being reads it as her having thrown.
+export const unreached = () => word('unreached');
+export const isUnreached = (x) => isWord(x) && wordOf(x) === 'unreached';

package/dist/being/types.d.ts

@@ -0,0 +1,89 @@
+import type { silence } from './silence.ts';
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type JsonObject = {
+    [key: string]: Json;
+};
+export type Asker = {
+    id: string;
+} | {
+    id?: undefined;
+};
+export declare const OWNER = "OWNER";
+export declare const PUBLIC = "PUBLIC";
+export declare const RESERVED_IDS: readonly string[];
+export type Invitation = {
+    ward: string;
+    heir?: string;
+    secret?: string;
+};
+export declare const invitationArgs: (inv: Invitation) => JsonObject;
+export declare const isInvitation: (v: unknown) => v is Invitation;
+export type Schema = JsonObject;
+export type Ask = {
+    name: string;
+    description?: string;
+    input: Schema;
+    output?: Schema;
+};
+export type Blueprint = {
+    asks: Ask[];
+    notes: Json;
+};
+export declare const isBlueprint: (v: unknown) => v is Blueprint;
+export type StandingRecord = {
+    id: string;
+    digest: string | null;
+    blueprint: Blueprint | null;
+    seen: string | null;
+};
+export type OccupantRecord = {
+    id: string;
+    notes: JsonObject;
+};
+export type Cells = {
+    standings: Record<string, StandingRecord>;
+    occupants: Record<string, OccupantRecord>;
+    [hers: string]: Json;
+};
+export type Silence = typeof silence;
+export type DoorWord = 'removed' | 'absent' | 'unannounced' | 'repeated' | 'threw';
+export type WardWord = 'unreached' | 'late' | 'invitation' | 'dropped';
+export type WordName = DoorWord | WardWord;
+export declare const WORD_KEY: unique symbol;
+export type Word<W extends WordName = WordName> = {
+    readonly [K in typeof WORD_KEY]: W;
+};
+export type Unreached = Word<'unreached'>;
+export type Answer = Json | Silence | Word;
+export type Reply = Json | Silence;
+export type Wanted = {
+    time?: number;
+};
+export type Standing = {
+    readonly id: string;
+    ask(method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+};
+export type Standings = {
+    knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+    take(id: string, invitation: Invitation): Promise<string | null>;
+    remove(id: string): void;
+} & {
+    readonly [id: string]: Standing | undefined;
+};
+export type Occupants = {
+    invite(id: string, notes?: JsonObject): Promise<Invitation | null>;
+    remove(id: string): void;
+};
+export type Stance = {
+    readonly cells: Cells;
+    readonly occupants: Occupants;
+    readonly standings: Standings;
+    lend(name: string, id: string): Promise<string | null>;
+    boot(className: string, key: string, id?: string): Promise<string | null>;
+};
+export interface BeingLike {
+    answer(asker: Asker, method?: string, args?: JsonObject): Reply | Promise<Reply>;
+}
+export type BeingClass = new (stance: Stance) => BeingLike;

package/dist/being/types.js

@@ -0,0 +1,58 @@
+// The ids the ward speaks under, and no being may mint. An asker id is hers:
+// she chooses the strings, and the ward has no business in her namespace. But
+// the ward must sometimes stand at her door itself — its describe asks every
+// being under OWNER — and an id it shares with one of her occupants is two
+// different parties wearing one name. She could not tell them apart, and the
+// ward would shape its describe through an occupant's gate.
+//
+// So the ward's words are shouted, and refused at the mint. A word can only
+// be reserved before anyone has used it: a partition already holding an
+// occupant of that name could never have it taken back. PUBLIC guards nothing
+// today — a public asker is {} and carries no id at all — and that is exactly
+// why it is claimed now, while claiming it is free.
+export const OWNER = 'OWNER';
+export const PUBLIC = 'PUBLIC';
+export const RESERVED_IDS = [OWNER, PUBLIC];
+// An invitation as one object of values, which is what it already is. A being
+// who hands one on sends it as args, and args are values; this is the one
+// place that is spelled, so nobody spells it with a cast. Absent stays absent:
+// an invitation to a public being carries no heir and no secret, and a key
+// present and undefined is not the same object once JSON has been through it.
+export const invitationArgs = (inv) => ({
+    ward: inv.ward,
+    ...(inv.heir !== undefined ? { heir: inv.heir } : {}),
+    ...(inv.secret !== undefined ? { secret: inv.secret } : {}),
+});
+// Whether a value that arrived is an invitation. The shape is the spec's, so
+// the reading of it is too, and it is one reading: a form that
+// asks a guest for one, a faculty handed one to wake her maker by, and a
+// shell that finds one in a link all ask the same question, and a kinder
+// answer in one of them is a value that fails at a door instead of at the
+// edge it came in by. A ward pk is a hundred and twenty-eight lowercase hex,
+// and a heir comes with its secret or neither comes: an invitation to a
+// public being carries no heir, and a heir with no secret opens nothing.
+export const isInvitation = (v) => {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const o = v;
+    if (typeof o.ward !== 'string' || !/^[0-9a-f]{128}$/.test(o.ward))
+        return false;
+    const heir = typeof o.heir === 'string', secret = typeof o.secret === 'string';
+    return (heir && secret) || (!heir && !secret && !('heir' in o) && !('secret' in o));
+};
+// Whether what came back from an empty ask is a blueprint. Every describe on
+// the far side of a door is somebody else's code, so nothing may be written
+// into a standing's record as a blueprint without being read as one first: a
+// side walks `asks` by name, and a list of anything else, or no list at all,
+// is a side that breaks on a far ward's answer. The asks are checked to the
+// depth a side reads them, a name and an input each, and no further: what a
+// far being puts beside those is hers.
+export const isBlueprint = (v) => {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const { asks, notes } = v;
+    if (!Array.isArray(asks) || notes === undefined)
+        return false;
+    return asks.every((a) => a !== null && typeof a === 'object' && !Array.isArray(a) && typeof a.name === 'string' && a.input !== null && typeof a.input === 'object' && !Array.isArray(a.input));
+};
+export const WORD_KEY = Symbol.for('quo.word');

package/dist/conformance/assert.d.ts

@@ -0,0 +1,11 @@
+export declare class Failed extends Error {
+}
+export declare function same(a: unknown, b: unknown): boolean;
+export type Assert = {
+    ok(value: unknown, message?: string): asserts value;
+    equal(actual: unknown, expected: unknown, message?: string): void;
+    notEqual(actual: unknown, expected: unknown, message?: string): void;
+    deepEqual(actual: unknown, expected: unknown, message?: string): void;
+    match(actual: string, re: RegExp, message?: string): void;
+};
+export declare const assert: Assert;

package/dist/conformance/assert.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+// The five assertions the conformance suite makes, and no more. Node has all
+// five in `node:assert/strict`, and naming that module would tie the suite to
+// one terrain -- the suite is the ward's truth, and the ward's truth has to be
+// checkable wherever a ward runs. So they are written here, in the language
+// alone, and `test/assert.test.ts` holds them to Node's own behaviour.
+export class Failed extends Error {
+}
+const show = (v) => {
+    if (typeof v === 'symbol')
+        return v.toString();
+    if (typeof v === 'bigint')
+        return `${v}n`;
+    if (v === undefined)
+        return 'undefined';
+    if (typeof v === 'function')
+        return `[function ${v.name}]`;
+    // A ward's word is a frozen object under one symbol key, and JSON shows it
+    // as `{}`. A red estate chapter saying `{} is not {}` names nothing, so a
+    // value whose own keys are all symbols is shown by its keys.
+    if (v !== null && typeof v === 'object') {
+        const keys = Object.keys(v);
+        const syms = Object.getOwnPropertySymbols(v).filter((s) => Object.getOwnPropertyDescriptor(v, s).enumerable);
+        if (keys.length === 0 && syms.length > 0)
+            return `{ ${syms.map((s) => `${s.toString()}: ${show(v[s])}`).join(', ')} }`;
+    }
+    try {
+        return JSON.stringify(v) ?? Object.prototype.toString.call(v);
+    }
+    catch {
+        return Object.prototype.toString.call(v); // a cycle, or a null prototype
+    }
+};
+const fail = (why, message) => {
+    throw new Failed(message ? `${message}: ${why}` : why);
+};
+// Structural, and strict about shape the way `node:assert/strict` is: a value
+// is not equal to one of another kind, and an array is not equal to an object
+// that happens to hold the same keys.
+// The four kinds this compares, and every other object is refused rather than
+// guessed at. A Date, a RegExp, a boxed primitive and a class instance each
+// carry state no key walk can see, so two of them with the same keys are
+// equal here and unequal in node, which is a wrong yes: the one answer a
+// suite must never give. A refusal is a red test that says so.
+const KNOWN = [Object.prototype, null, Array.prototype, Uint8Array.prototype];
+// What node compares: own enumerable keys, strings then enumerable symbols.
+// Not `Reflect.ownKeys`, which also lists what a definition hid.
+const keysOf = (v) => [...Object.keys(v), ...Object.getOwnPropertySymbols(v).filter((s) => Object.getOwnPropertyDescriptor(v, s).enumerable)];
+export function same(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    const proto = Object.getPrototypeOf(a);
+    if (proto !== Object.getPrototypeOf(b))
+        return false;
+    if (!KNOWN.includes(proto))
+        return false; // a Date, a RegExp, a boxed number, a class of hers
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (a instanceof Uint8Array && b instanceof Uint8Array)
+        return a.length === b.length && a.every((x, i) => x === b[i]);
+    // An array is its indices and whatever else was hung on it, and a hole is
+    // not a present undefined: `[, 1]` and `[undefined, 1]` differ in node and
+    // must differ here. `every` skips holes, so the loop is written out.
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i += 1) {
+            if (i in a !== i in b)
+                return false;
+            if (i in a && !same(a[i], b[i]))
+                return false;
+        }
+        const extra = (v) => keysOf(v).filter((k) => typeof k !== 'string' || !/^(?:0|[1-9]\d*)$/.test(k));
+        const xa = extra(a), xb = extra(b);
+        const at = (v, k) => v[k];
+        return xa.length === xb.length && xa.every((k) => xb.includes(k) && same(at(a, k), at(b, k)));
+    }
+    const ka = keysOf(a), kb = keysOf(b);
+    if (ka.length !== kb.length)
+        return false;
+    return ka.every((k) => kb.includes(k) && same(a[k], b[k]));
+}
+export const assert = {
+    ok(value, message) {
+        if (!value)
+            fail(`${show(value)} is not truthy`, message);
+    },
+    equal(actual, expected, message) {
+        if (!Object.is(actual, expected))
+            fail(`${show(actual)} !== ${show(expected)}`, message);
+    },
+    notEqual(actual, expected, message) {
+        if (Object.is(actual, expected))
+            fail(`${show(actual)} === ${show(expected)}`, message);
+    },
+    deepEqual(actual, expected, message) {
+        if (!same(actual, expected))
+            fail(`${show(actual)} is not ${show(expected)}`, message);
+    },
+    match(actual, re, message) {
+        if (typeof actual !== 'string' || !re.test(actual))
+            fail(`${show(actual)} does not match ${String(re)}`, message);
+    },
+};

package/dist/conformance/beings.d.ts

@@ -0,0 +1,198 @@
+import { Being } from '../being/being.ts';
+import type { Asker, Blueprint, Invitation, Json, JsonObject, OccupantRecord, Reply, Stance } from '../being/types.ts';
+export declare class Printer extends Being {
+    static cells: {
+        jobs: JsonObject[];
+        asks: JsonObject[];
+    };
+    static asks: {
+        print: {
+            input: {
+                type: string;
+            };
+        };
+    };
+    describe(): Blueprint;
+    print({ doc }: JsonObject, asker: Asker): {
+        printed: string | number | boolean | Json[] | {
+            [key: string]: Json;
+        } | null;
+    };
+}
+export declare class Shop extends Being {
+    static cells: {
+        printerId: string | null;
+        sales: JsonObject[];
+        minted: number;
+    };
+    static asks: {
+        hello: {
+            input: {
+                type: string;
+            };
+        };
+        buy: {
+            input: {
+                type: string;
+                properties: {
+                    item: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        refund: {
+            input: {
+                type: string;
+            };
+            for: (rec: OccupantRecord | undefined) => boolean;
+        };
+    };
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+    invite(tier?: string): Promise<Invitation>;
+    keepPrinter(invitation: Invitation): Promise<boolean>;
+    hello({ invitation }: JsonObject, asker: Asker): Promise<{
+        welcome: boolean;
+    }>;
+    buy({ item }: JsonObject, asker: Asker): Promise<{
+        error: string;
+        retry?: undefined;
+        ok?: undefined;
+        receipt?: undefined;
+    } | {
+        error: string;
+        retry: boolean;
+        ok?: undefined;
+        receipt?: undefined;
+    } | {
+        error?: undefined;
+        retry?: undefined;
+        ok: boolean;
+        receipt: Json;
+    }>;
+    refund(): {
+        ok: boolean;
+    };
+}
+export declare class Customer extends Being {
+    static cells: {
+        heard: JsonObject[];
+    };
+    static asks: {
+        hi: {
+            input: {
+                type: string;
+            };
+        };
+    };
+    join(invitation: Invitation): Promise<string | number | boolean | typeof import("../being/silence.ts").silence | Json[] | import("../being/types.ts").Word<import("../being/types.ts").WordName> | {
+        [key: string]: Json;
+    } | null>;
+    buy(item: string): Promise<import("../being/types.ts").Answer>;
+    learn(): Promise<import("../being/types.ts").Answer>;
+    hi(_args: JsonObject, asker: Asker): {
+        heard: string;
+    };
+}
+export declare class Echo {
+    s: Stance;
+    constructor(stance: Stance);
+    answer(asker: Asker, method?: string, args?: JsonObject): Reply;
+}
+export declare class Maker extends Being {
+    static cells: {
+        made: string[];
+    };
+    static asks: {
+        open: {
+            input: {
+                type: string;
+                properties: {
+                    class: {
+                        type: string;
+                    };
+                    key: {
+                        type: string;
+                    };
+                    id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        say: {
+            input: {
+                type: string;
+                properties: {
+                    id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        borrow: {
+            input: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                    id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+    };
+    open({ class: className, key, id }: JsonObject): Promise<{
+        made: string | null;
+    }>;
+    say({ id }: JsonObject): Promise<{
+        said: Json;
+    }>;
+    borrow({ name, id }: JsonObject): Promise<{
+        lent: string | null;
+    }>;
+}
+export declare class Member extends Being {
+    static cells: {
+        heard: JsonObject[];
+    };
+    static asks: {
+        ping: {
+            input: {
+                type: string;
+            };
+        };
+        relay: {
+            input: {
+                type: string;
+                properties: {
+                    id: {
+                        type: string;
+                    };
+                    method: {
+                        type: string;
+                    };
+                    time: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+    };
+    ping(_args: JsonObject, asker: Asker): {
+        pong: string | null;
+    };
+    relay({ id, method, args, time }: JsonObject): Promise<{
+        said: string;
+        out: null;
+    } | {
+        said: null;
+        out: Json;
+    }>;
+}