@toa.io/core 1.0.0-alpha.31 → 1.0.0-alpha.311

package/transpiled/connector.d.ts

@@ -0,0 +1,71 @@
+/** Abstract connections hierarchy */
+export declare class Connector {
+    #private;
+    readonly id: string;
+    connected: boolean;
+    /**
+     * Whether this has been taken down. What is disposed of is never connected again: a
+     * communication it held is sealed, an announcement it made has stopped, an algorithm it ran
+     * is unmounted. Whoever remembers one for the life of the process — an extension factory
+     * caching what it hands to components — replaces it rather than handing it out twice.
+     */
+    disposed: boolean;
+    constructor();
+    /**
+     * Creates a dependency and backlink with another Connector or a set of Connectors
+     *
+     * See .connect() and .disconnect()
+     *
+     */
+    depends(connector: Connector | Connector[]): Connector;
+    /**
+     * Creates a backlink to another Connector
+     *
+     * See .connect() and .disconnect()
+     *
+     */
+    link(connector: Connector): void;
+    /**
+     * Connects dependants then self
+     *
+     * In case of exception disconnects with current connection interruption
+     *
+     * Method is idempotent
+     *
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects self then dependants
+     *
+     * Does nothing if there are connected linked Connectors
+     *
+     * Method is idempotent
+     *
+     */
+    disconnect(interrupt?: boolean): Promise<void>;
+    reconnect(): Promise<void>;
+    debug(node?: Record<string, any>): Record<string, any>;
+    /** Called on connection */
+    /**
+     * Stops what this tree does of its own accord, holding every connection open.
+     *
+     * The walk is what reaches a connector; what the connector does about it is `stop`. Top down,
+     * so a source is stopped before whatever it feeds, and a failure is reported rather than
+     * raised — one connector that will not stop is no reason to leave the rest working.
+     */
+    halt(visited?: Set<Connector>): Promise<void>;
+    /**
+     * Starts again what `halt` stopped, bottom up, so nothing works before what it works through.
+     * Runs wherever the halt went, including where it failed.
+     */
+    restore(visited?: Set<Connector>): Promise<void>;
+    /** What this stops doing of its own accord while the tree is halted. See `halt`. */
+    protected pause(): Promise<void> | void;
+    /** What it starts doing again. See `restore`. */
+    protected unpause(): Promise<void> | void;
+    protected open(): Promise<void> | void;
+    /** Called on disconnection */
+    protected close(): Promise<void> | void;
+    /** Called after self and dependants disconnection is complete */
+    protected dispose(): Promise<void> | void;
+}

package/transpiled/connector.js

@@ -0,0 +1,248 @@
+import { console } from 'openspan';
+import { environment } from '@toa.io/generic';
+/** Abstract connections hierarchy */
+export class Connector {
+    #dependencies = [];
+    #links = [];
+    #connecting;
+    #disconnecting;
+    #discarded = false;
+    /** Whether this has been told to stop what it does of its own accord, see `halt`. */
+    #halted = false;
+    id;
+    connected = false;
+    /**
+     * Whether this has been taken down. What is disposed of is never connected again: a
+     * communication it held is sealed, an announcement it made has stopped, an algorithm it ran
+     * is unmounted. Whoever remembers one for the life of the process — an extension factory
+     * caching what it hands to components — replaces it rather than handing it out twice.
+     */
+    disposed = false;
+    constructor() {
+        this.id = this.constructor.name + '#' + Math.random().toString(36).substring(2, 8);
+    }
+    /**
+     * Creates a dependency and backlink with another Connector or a set of Connectors
+     *
+     * See .connect() and .disconnect()
+     *
+     */
+    depends(connector) {
+        let next;
+        if (connector instanceof Array) {
+            if (connector.length === 0)
+                throw new Error('Connectors array must not be empty');
+            if (connector.length > 1) {
+                next = new Connector();
+                for (const item of connector) {
+                    this.#dependencies.push(item);
+                    item.depends(next);
+                }
+            }
+            else
+                next = connector[0];
+        }
+        else
+            next = connector;
+        this.#dependencies.push(next);
+        next.link(this);
+        // See .#discard()
+        if (this.#disconnecting !== undefined)
+            next.#discard();
+        // and the same for a quiescence the walk has gone past already: one taken on after it
+        // would otherwise be the one thing in the tree still working
+        if (this.#halted)
+            void next.halt();
+        return next;
+    }
+    /**
+     * Disconnects, now and again if a connection is still to land.
+     *
+     * A dependency taken on after its dependant was disconnected — a lookup that returns
+     * once the teardown walk has gone by — is one nothing is left to take down, as the
+     * walk that would have reached it is over. One that stays connected holds open
+     * everything it depends on with it: a dependency reads `connected` of every dependant
+     * before it closes, and a dependant that is connected for good is a dependency that
+     * never closes.
+     */
+    #discard() {
+        this.#discarded = true;
+        // one that is up already, or on its way, is taken down here; one that is not is
+        // taken down by the connection when it comes, and until then there is nothing to do
+        if (this.#connecting !== undefined)
+            void this.#drop();
+    }
+    /**
+     * Creates a backlink to another Connector
+     *
+     * See .connect() and .disconnect()
+     *
+     */
+    link(connector) {
+        this.#links.push(connector);
+    }
+    /**
+     * Connects dependants then self
+     *
+     * In case of exception disconnects with current connection interruption
+     *
+     * Method is idempotent
+     *
+     */
+    async connect() {
+        if (this.#connecting)
+            return this.#connecting;
+        this.#disconnecting = undefined;
+        const work = async () => {
+            await Promise.all(this.#dependencies.map((connector) => connector.connect()));
+            await this.open();
+        };
+        // anonymous grouping nodes are not worth a span
+        const connecting = TRACE_BOOT && this.constructor.name !== 'Connector'
+            ? console.span({
+                name: `connect ${this.constructor.name}`,
+                // a connector that has a locator is named by it; a grouping node has none
+                attributes: { id: this.locator?.id ?? this.id }
+            }, work)
+            : work();
+        this.#connecting = connecting;
+        try {
+            await connecting;
+            /*
+             * A disconnection that did not wait for this connection emptied `#connecting` to
+             * say so. Reporting `connected` now would report it of a connector nothing takes
+             * down again — its `#disconnecting` has settled, so a later call returns at once —
+             * and what it depends on reads that of every dependant before it closes.
+             */
+            if (this.#connecting === connecting)
+                this.connected = true;
+        }
+        catch (e) {
+            await this.disconnect(true);
+            throw e;
+        }
+        // a connection asked for before this one was discarded, landing after. See .#discard()
+        if (this.#discarded)
+            await this.#drop();
+    }
+    /** Disconnects a discarded connector, saying so rather than throwing at whoever is not waiting. */
+    async #drop() {
+        this.#discarded = false;
+        try {
+            await this.disconnect();
+        }
+        catch (error) {
+            console.error('Discarded connector failed to disconnect', { id: this.id, error });
+        }
+    }
+    /**
+     * Disconnects self then dependants
+     *
+     * Does nothing if there are connected linked Connectors
+     *
+     * Method is idempotent
+     *
+     */
+    async disconnect(interrupt) {
+        // a connector that has not finished connecting has nothing to close, and
+        // awaiting a connection that may never settle outlives any grace period
+        const pending = interrupt === true || this.connected === false;
+        if (!pending)
+            await this.#connecting;
+        if (this.#disconnecting)
+            return this.#disconnecting;
+        const linked = this.#links.reduce((acc, parent) => acc || parent.connected, false);
+        if (linked && interrupt !== true)
+            return;
+        this.#disconnecting = (async () => {
+            const start = +new Date();
+            const interval = setInterval(() => {
+                const delay = +new Date() - start;
+                if (delay > DELAY)
+                    console.warn(`Connector ${this.id} still disconnecting (${delay})`);
+            }, DELAY);
+            if (!pending)
+                await this.close();
+            // said once the closing is done rather than when it starts: a dependant that is
+            // still closing is still using what it depends on, and the check above reads this
+            // of every dependant. Saying it early lets the first to start tear down a shared
+            // dependency under the others.
+            this.connected = false;
+            this.#connecting = undefined;
+            clearInterval(interval);
+            await Promise.all(this.#dependencies.map((connector) => connector.disconnect()));
+            await this.dispose();
+            this.disposed = true;
+        })();
+        await this.#disconnecting;
+    }
+    async reconnect() {
+        await this.disconnect();
+        await this.connect();
+    }
+    debug(node = {}) {
+        node[this.id] = { connected: this.connected };
+        if (this.#dependencies.length > 0)
+            for (const connector of this.#dependencies)
+                connector.debug?.(node[this.id]);
+        return node;
+    }
+    /** Called on connection */
+    /**
+     * Stops what this tree does of its own accord, holding every connection open.
+     *
+     * The walk is what reaches a connector; what the connector does about it is `stop`. Top down,
+     * so a source is stopped before whatever it feeds, and a failure is reported rather than
+     * raised — one connector that will not stop is no reason to leave the rest working.
+     */
+    async halt(visited = new Set()) {
+        // the walk is governed by where it has been, and the flag only by whether this one has
+        // already stopped: a connector that has, with a subtree that has not, is still walked through
+        if (visited.has(this))
+            return;
+        visited.add(this);
+        if (!this.#halted) {
+            this.#halted = true;
+            try {
+                await this.pause();
+            }
+            catch (error) {
+                console.error('Connector failed to pause', { id: this.id, error });
+            }
+        }
+        for (const dependency of this.#dependencies)
+            await dependency.halt(visited);
+    }
+    /**
+     * Starts again what `halt` stopped, bottom up, so nothing works before what it works through.
+     * Runs wherever the halt went, including where it failed.
+     */
+    async restore(visited = new Set()) {
+        if (visited.has(this))
+            return;
+        visited.add(this);
+        for (const dependency of this.#dependencies)
+            await dependency.restore(visited);
+        if (!this.#halted)
+            return;
+        this.#halted = false;
+        try {
+            await this.unpause();
+        }
+        catch (error) {
+            console.error('Connector failed to unpause', { id: this.id, error });
+        }
+    }
+    /** What this stops doing of its own accord while the tree is halted. See `halt`. */
+    pause() { }
+    /** What it starts doing again. See `restore`. */
+    unpause() { }
+    open() { }
+    /** Called on disconnection */
+    close() { }
+    /** Called after self and dependants disconnection is complete */
+    dispose() { }
+}
+const DELAY = 5000;
+const TRACE_BOOT = environment.get('TOA_BOOT_TRACE') === '1';
+//# sourceMappingURL=connector.js.map

package/transpiled/connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../source/connector.ts"],"names":[],"mappings":"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"}

package/transpiled/context.d.ts

@@ -0,0 +1,25 @@
+import { Connector } from './connector.ts';
+import type { Locator } from './locator.ts';
+import type { Component } from './component.ts';
+import type { Remote } from './remote.ts';
+import type { Aspect } from './types/extensions.ts';
+import type { Options, Request } from './types/request.ts';
+type Discover = (namespace: string, name: string) => Promise<Remote>;
+export declare class Context extends Connector {
+    #private;
+    readonly env: string | undefined;
+    readonly name: string | undefined;
+    /**
+     * The rank of the region this deployment is, which is what its writes are stamped with. A
+     * deployment that is no region at all reads as zero, which is what its records carry.
+     */
+    readonly region: number;
+    readonly aspects: Aspect[];
+    readonly locator: Locator;
+    /** The name this process answers addressed calls under. */
+    readonly instance: string;
+    constructor(local: Component, discover: Discover, aspects?: Aspect[]);
+    apply(endpoint: string, request: Request, options?: Options): Promise<any>;
+    call(namespace: string, name: string, endpoint: string, request: Request, options?: Options): Promise<any>;
+}
+export {};

package/transpiled/context.js

@@ -0,0 +1,55 @@
+import { Connector } from './connector.js';
+import { waiting } from './abandon.js';
+import { instance } from './instance.js';
+import { environment } from '@toa.io/generic';
+export class Context extends Connector {
+    env;
+    name;
+    /**
+     * The rank of the region this deployment is, which is what its writes are stamped with. A
+     * deployment that is no region at all reads as zero, which is what its records carry.
+     */
+    region;
+    aspects;
+    locator;
+    /** The name this process answers addressed calls under. */
+    instance;
+    #local;
+    #discover;
+    #remotes = {};
+    constructor(local, discover, aspects = []) {
+        super();
+        this.env = environment.get('TOA_ENV');
+        this.name = environment.get('TOA_CONTEXT');
+        this.region = Number(environment.get('TOA_REGION') ?? 0);
+        this.aspects = aspects;
+        this.locator = local?.locator;
+        this.instance = instance();
+        this.#local = local;
+        this.#discover = discover;
+        this.depends(local);
+        if (aspects.length > 0)
+            this.depends(aspects);
+    }
+    async apply(endpoint, request, options) {
+        return this.#local.invoke(endpoint, request, options);
+    }
+    // eslint-disable-next-line max-params
+    async call(namespace, name, endpoint, request, options) {
+        // the lookup is waited for as the call is: a caller that stops waiting is answered at once, and
+        // the lookup finishes for the next call to use
+        const remote = await waiting(this.#remote(namespace, name), options?.signal, `${namespace}.${name}.${endpoint}`);
+        return remote.invoke(endpoint, request, options);
+    }
+    async #remote(namespace, name) {
+        const key = namespace + '.' + name;
+        this.#remotes[key] ??= this.#connect(namespace, name);
+        return this.#remotes[key];
+    }
+    async #connect(namespace, name) {
+        const remote = await this.#discover(namespace, name);
+        this.depends(remote);
+        return remote;
+    }
+}
+//# sourceMappingURL=context.js.map

package/transpiled/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../source/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAS7C,MAAM,OAAO,OAAQ,SAAQ,SAAS;IACpB,GAAG,CAAoB;IACvB,IAAI,CAAoB;IAExC;;;OAGG;IACa,MAAM,CAAQ;IAEd,OAAO,CAAU;IACjB,OAAO,CAAS;IAEhC,2DAA2D;IAC3C,QAAQ,CAAQ;IAEvB,MAAM,CAAW;IACjB,SAAS,CAAU;IACnB,QAAQ,GAAoC,EAAE,CAAA;IAEvD,YAAmB,KAAgB,EAAE,QAAkB,EAAE,OAAO,GAAa,EAAE;QAC7E,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QACrC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;QAC1C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;QACxD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,OAAO,GAAG,KAAK,EAAE,OAAO,CAAA;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,EAAE,CAAA;QAE1B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;QACnB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QAEzB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAEnB,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/C,CAAC;IAEM,KAAK,CAAC,KAAK,CAAC,QAAgB,EAAE,OAAgB,EAAE,OAAiB;QACtE,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACvD,CAAC;IAED,sCAAsC;IAC/B,KAAK,CAAC,IAAI,CACf,SAAiB,EACjB,IAAY,EACZ,QAAgB,EAChB,OAAgB,EAChB,OAAiB;QAEjB,gGAAgG;QAChG,+CAA+C;QAC/C,MAAM,MAAM,GAAG,MAAM,OAAO,CAC1B,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,EAC7B,OAAO,EAAE,MAAM,EACf,GAAG,SAAS,IAAI,IAAI,IAAI,QAAQ,EAAE,CACnC,CAAA;QAED,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IAClD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,IAAY;QAC3C,MAAM,GAAG,GAAG,SAAS,GAAG,GAAG,GAAG,IAAI,CAAA;QAElC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;QAErD,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC3B,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,SAAiB,EAAE,IAAY;QAC5C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;QAEpD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QAEpB,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}

package/transpiled/contract/component.d.ts

@@ -0,0 +1,24 @@
+import type { Definition, Entity } from './request.ts';
+/** What a caller is given in order to call a component: what a map states of it. */
+export interface Contract {
+    /** the version of the component this describes */
+    version?: string;
+    entity?: Entity;
+    operations?: Record<string, Operation>;
+    events?: Record<string, Event>;
+}
+export interface Operation extends Definition {
+    bindings?: string[];
+}
+export interface Event {
+    binding: string;
+}
+/**
+ * What a caller is given of a component, of what its normalised manifest holds.
+ *
+ * What a component states about serving a call rather than about making one is its own: an
+ * operation's concurrency, the bridge that runs it and what it forwards to, and the entity's
+ * storage, its blank and its migrations. An event's `path` is a path in the process that
+ * normalised the manifest, and names nothing in any other.
+ */
+export declare function component(manifest: Contract): Contract;

package/transpiled/contract/component.js

@@ -0,0 +1,48 @@
+/**
+ * What a caller is given of a component, of what its normalised manifest holds.
+ *
+ * What a component states about serving a call rather than about making one is its own: an
+ * operation's concurrency, the bridge that runs it and what it forwards to, and the entity's
+ * storage, its blank and its migrations. An event's `path` is a path in the process that
+ * normalised the manifest, and names nothing in any other.
+ */
+export function component(manifest) {
+    const contract = { version: manifest.version };
+    if (manifest.entity !== undefined)
+        contract.entity = {
+            properties: manifest.entity.properties,
+            required: manifest.entity.required
+        };
+    if (manifest.operations !== undefined) {
+        contract.operations = {};
+        for (const [endpoint, definition] of Object.entries(manifest.operations))
+            contract.operations[endpoint] = operation(definition);
+    }
+    if (manifest.events !== undefined) {
+        contract.events = {};
+        for (const [event, definition] of Object.entries(manifest.events))
+            contract.events[event] = { binding: definition.binding };
+    }
+    return contract;
+}
+function operation(definition) {
+    const operation = {};
+    for (const key of KEYS)
+        if (definition[key] !== undefined)
+            operation[key] = definition[key];
+    return operation;
+}
+/** What a call to an operation is addressed by, carries, answers and refuses with. */
+const KEYS = [
+    'type',
+    'scope',
+    'query',
+    'once',
+    'stateful',
+    'bindings',
+    'description',
+    'input',
+    'output',
+    'errors'
+];
+//# sourceMappingURL=component.js.map

package/transpiled/contract/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../source/contract/component.ts"],"names":[],"mappings":"AAmBA;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,QAAkB;IAC1C,MAAM,QAAQ,GAAa,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAA;IAExD,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;QAC/B,QAAQ,CAAC,MAAM,GAAG;YAChB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU;YACtC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ;SACnC,CAAA;IAEH,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACtC,QAAQ,CAAC,UAAU,GAAG,EAAE,CAAA;QAExB,KAAK,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;YACtE,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;IACzD,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,QAAQ,CAAC,MAAM,GAAG,EAAE,CAAA;QAEpB,KAAK,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC/D,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,CAAA;IAC5D,CAAC;IAED,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,SAAS,SAAS,CAAC,UAAqB;IACtC,MAAM,SAAS,GAA4B,EAAE,CAAA;IAE7C,KAAK,MAAM,GAAG,IAAI,IAAI;QACpB,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,SAAS,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;IAErE,OAAO,SAAsB,CAAA;AAC/B,CAAC;AAED,sFAAsF;AACtF,MAAM,IAAI,GAAG;IACX,MAAM;IACN,OAAO;IACP,OAAO;IACP,MAAM;IACN,UAAU;IACV,UAAU;IACV,aAAa;IACb,OAAO;IACP,QAAQ;IACR,QAAQ;CACiC,CAAA"}

package/transpiled/contract/contract.d.ts

@@ -0,0 +1,10 @@
+import type { Schema, SchemaError } from '@toa.io/schemas';
+import type { Exception } from '../exceptions.ts';
+/** What a contract throws with, stated by the subclass. */
+export type Refusal = new (error: SchemaError, cause?: unknown) => Exception;
+export declare class Contract {
+    readonly schema: Schema;
+    static Exception: Refusal;
+    constructor(schema: Schema);
+    fit(value: unknown): void;
+}

package/transpiled/contract/contract.js

@@ -0,0 +1,14 @@
+import { SystemException } from '../exceptions.js';
+export class Contract {
+    schema;
+    static Exception = SystemException;
+    constructor(schema) {
+        this.schema = schema;
+    }
+    fit(value) {
+        const error = this.schema.fit(value);
+        if (error !== null)
+            throw new this.constructor.Exception(error, value);
+    }
+}
+//# sourceMappingURL=contract.js.map

package/transpiled/contract/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../source/contract/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAOlD,MAAM,OAAO,QAAQ;IACH,MAAM,CAAQ;IAEvB,MAAM,CAAC,SAAS,GAAY,eAAqC,CAAA;IAExE,YAAmB,MAAc;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAEM,GAAG,CAAC,KAAc;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAEpC,IAAI,KAAK,KAAK,IAAI;YAChB,MAAM,IAAK,IAAI,CAAC,WAA+B,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;IAC3E,CAAC;CACF"}

package/transpiled/contract/index.d.ts

@@ -0,0 +1,3 @@
+export { component } from './component.ts';
+export { Request } from './request.ts';
+export { Reply } from './reply.ts';

package/transpiled/contract/index.js

@@ -0,0 +1,4 @@
+export { component } from './component.js';
+export { Request } from './request.js';
+export { Reply } from './reply.js';
+//# sourceMappingURL=index.js.map

package/transpiled/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA"}

package/transpiled/contract/reply.d.ts

@@ -0,0 +1,7 @@
+import { Contract } from './contract.ts';
+import type { Refusal } from './contract.ts';
+import type { JSONSchema } from './schemas.ts';
+export declare class Reply extends Contract {
+    static Exception: Refusal;
+    static schema(output?: JSONSchema, errors?: Array<string | number>): JSONSchema;
+}

package/transpiled/contract/reply.js

@@ -0,0 +1,48 @@
+import { Contract } from './contract.js';
+import { ResponseContractException } from '../exceptions.js';
+export class Reply extends Contract {
+    static Exception = ResponseContractException;
+    static schema(output, errors) {
+        const schema = {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        };
+        if (output !== undefined) {
+            /*
+             * A reply carries more than the operation declares — `VERSION` and the rest of the
+             * record's own fields — so what it is validated against is the declaration relaxed.
+             * On a copy: the declaration itself is what a component publishes when asked to
+             * explain, and relaxing that would publish a contract nobody wrote.
+             */
+            output = structuredClone(output);
+            if (output.type === 'object')
+                output.additionalProperties = true;
+            else if (output.type === 'array' && output.items?.type === 'object')
+                output.items.additionalProperties = true;
+            schema.properties.output = output;
+        }
+        /*
+         * An error a caller is meant to handle is one the operation states. Where none are
+         * stated, an error is not a reply this operation makes — it is a mistake, and the
+         * contract says so rather than passing an undeclared code on to whoever called.
+         */
+        schema.properties.error =
+            errors === undefined
+                ? false
+                : {
+                    type: 'object',
+                    properties: {
+                        code: {
+                            enum: errors
+                        },
+                        message: {
+                            type: 'string'
+                        }
+                    },
+                    required: ['code']
+                };
+        return schema;
+    }
+}
+//# sourceMappingURL=reply.js.map

package/transpiled/contract/reply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply.js","sourceRoot":"","sources":["../../source/contract/reply.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAA;AAI5D,MAAM,OAAO,KAAM,SAAQ,QAAQ;IAC1B,MAAM,CAAU,SAAS,GAC9B,yBAA+C,CAAA;IAE1C,MAAM,CAAC,MAAM,CAAC,MAAmB,EAAE,MAA+B;QACvE,MAAM,MAAM,GAAe;YACzB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE;YACd,oBAAoB,EAAE,KAAK;SAC5B,CAAA;QAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB;;;;;eAKG;YACH,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;YAEhC,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAA;iBAC3D,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,KAAK,QAAQ;gBACjE,MAAM,CAAC,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAAA;YAE1C,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,MAAM,CAAA;QACnC,CAAC;QAED;;;;WAIG;QACH,MAAM,CAAC,UAAU,CAAC,KAAK;YACrB,MAAM,KAAK,SAAS;gBAClB,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC;oBACE,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,IAAI,EAAE;4BACJ,IAAI,EAAE,MAAM;yBACb;wBACD,OAAO,EAAE;4BACP,IAAI,EAAE,QAAQ;yBACf;qBACF;oBACD,QAAQ,EAAE,CAAC,MAAM,CAAC;iBACnB,CAAA;QAEP,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}

package/transpiled/contract/request.d.ts

@@ -0,0 +1,39 @@
+import { Contract } from './contract.ts';
+import type { Schema } from '@toa.io/schemas';
+import type { Refusal } from './contract.ts';
+import type { JSONSchema } from './schemas.ts';
+/** What an operation states about itself, and answers when asked to explain. */
+export interface Explanation {
+    description?: string;
+    /**
+     * Whether the same call arriving twice changes state once. Said, because a caller cannot tell
+     * it from an answer that says nothing, and what it changes is whether a retry is safe to make.
+     */
+    once?: boolean;
+    /**
+     * Whether a call to it names the process it goes to. Said, because the caller is the one who
+     * has to name one, and a call that names none is refused.
+     */
+    stateful?: boolean;
+    input?: JSONSchema | null;
+    output?: JSONSchema | null;
+    errors?: Array<string | number>;
+}
+export interface Definition extends Explanation {
+    type?: string;
+    scope?: string;
+    query?: boolean;
+}
+/** What the operation works on, as the manifest declares it. */
+export interface Entity {
+    properties: Record<string, JSONSchema>;
+    required?: string[];
+}
+export declare class Request extends Contract {
+    readonly discovery: Explanation;
+    static Exception: Refusal;
+    constructor(schema: Schema, definition: Definition, entity?: Entity);
+    static schema(definition: Definition, entity?: {
+        properties: Record<string, JSONSchema>;
+    }): JSONSchema;
+}