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

package/transpiled/halting.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Whether this process is halting.
+ *
+ * A halt is the one teardown that is not a shutdown: the process stays, and what it held is
+ * built again. Two things read this and act differently because of it — a connection gives up
+ * the replies it is waiting for rather than holding the teardown open for a peer that is
+ * halting too, and a rejection from a tree that has been taken down is reported rather than
+ * fatal, because the process is in exactly the state the runtime put it in.
+ *
+ * Ambient, like the instance name and the invocation chain, and for the same reason: a process
+ * may carry two copies of this module, and an answer from one of them answers for half a
+ * process.
+ */
+export declare function begin(): void;
+export declare function end(): void;
+export declare function underway(): boolean;

package/transpiled/halting.js

@@ -0,0 +1,25 @@
+/**
+ * Whether this process is halting.
+ *
+ * A halt is the one teardown that is not a shutdown: the process stays, and what it held is
+ * built again. Two things read this and act differently because of it — a connection gives up
+ * the replies it is waiting for rather than holding the teardown open for a peer that is
+ * halting too, and a rejection from a tree that has been taken down is reported rather than
+ * fatal, because the process is in exactly the state the runtime put it in.
+ *
+ * Ambient, like the instance name and the invocation chain, and for the same reason: a process
+ * may carry two copies of this module, and an answer from one of them answers for half a
+ * process.
+ */
+const KEY = Symbol.for('toa.core.halting');
+const store = (globalThis[KEY] ??= { underway: false });
+export function begin() {
+    store.underway = true;
+}
+export function end() {
+    store.underway = false;
+}
+export function underway() {
+    return store.underway;
+}
+//# sourceMappingURL=halting.js.map

package/transpiled/halting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"halting.js","sourceRoot":"","sources":["../source/halting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;AAI1C,MAAM,KAAK,GAAG,CAAE,UAAoB,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;AAElE,MAAM,UAAU,KAAK;IACnB,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAA;AACvB,CAAC;AAED,MAAM,UAAU,GAAG;IACjB,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAA;AACxB,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,KAAK,CAAC,QAAQ,CAAA;AACvB,CAAC"}

package/transpiled/index.d.ts

@@ -0,0 +1,41 @@
+export { Assignment } from './assignment.ts';
+export { Call } from './call.ts';
+export { Cascade } from './cascade.ts';
+export { Component } from './component.ts';
+export { Composition } from './composition.ts';
+export { Connector } from './connector.ts';
+export { Context } from './context.ts';
+export { Encoded } from './encoded.ts';
+export { Effect } from './effect.ts';
+export { Emission } from './emission.ts';
+export { Event } from './event.ts';
+export { Gate } from './gate.ts';
+export { Locator } from './locator.ts';
+export { Observation } from './observation.ts';
+export { Outbox } from './outbox.ts';
+export { Operation } from './operation.ts';
+export { Query } from './query.ts';
+export { Receiver } from './receiver.ts';
+export { Reflection } from './reflection.ts';
+export { Remote } from './remote.ts';
+export { State } from './state.ts';
+export { Transition } from './transition.ts';
+export { Transmission } from './transmission.ts';
+export { Unmanaged } from './unmanaged.ts';
+export { Guard } from './guard.ts';
+export { instance } from './instance.ts';
+export { safe } from './safety.ts';
+export * as deliveries from './deliveries.ts';
+export * as entities from './entities/index.ts';
+export * as halting from './halting.ts';
+export * as exceptions from './exceptions.ts';
+export * as trail from './trail.ts';
+export * as contract from './contract/index.ts';
+export type { Exception } from './exceptions.ts';
+export type { Invocable } from './component.ts';
+export type { Explicable } from './remote.ts';
+export type { Scoped, Store } from './operation.ts';
+export type { Source as ReflectionSource } from './reflection.ts';
+export type { Explanation } from './contract/request.ts';
+export type { Contract } from './contract/component.ts';
+export type { JSONSchema } from './contract/schemas.ts';

package/transpiled/index.js

@@ -0,0 +1,34 @@
+export { Assignment } from './assignment.js';
+export { Call } from './call.js';
+export { Cascade } from './cascade.js';
+export { Component } from './component.js';
+export { Composition } from './composition.js';
+export { Connector } from './connector.js';
+export { Context } from './context.js';
+export { Encoded } from './encoded.js';
+export { Effect } from './effect.js';
+export { Emission } from './emission.js';
+export { Event } from './event.js';
+export { Gate } from './gate.js';
+export { Locator } from './locator.js';
+export { Observation } from './observation.js';
+export { Outbox } from './outbox.js';
+export { Operation } from './operation.js';
+export { Query } from './query.js';
+export { Receiver } from './receiver.js';
+export { Reflection } from './reflection.js';
+export { Remote } from './remote.js';
+export { State } from './state.js';
+export { Transition } from './transition.js';
+export { Transmission } from './transmission.js';
+export { Unmanaged } from './unmanaged.js';
+export { Guard } from './guard.js';
+export { instance } from './instance.js';
+export { safe } from './safety.js';
+export * as deliveries from './deliveries.js';
+export * as entities from './entities/index.js';
+export * as halting from './halting.js';
+export * as exceptions from './exceptions.js';
+export * as trail from './trail.js';
+export * as contract from './contract/index.js';
+//# sourceMappingURL=index.js.map

package/transpiled/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAClC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAA;AAC/C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAA"}

package/transpiled/instance.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The name this process answers addressed calls under, and what a call to one of its stateful
+ * operations names: given by `TOA_INSTANCE`, or generated once.
+ *
+ * It is kept where every copy of this package reads it, because a binding and a component loaded
+ * against two copies must agree on whose name a call carries.
+ */
+export declare function instance(): string;
+/** How long an addressed call waits where it names no timeout of its own, in milliseconds. */
+export declare function timeout(): number;

package/transpiled/instance.js

@@ -0,0 +1,30 @@
+import { environment } from '@toa.io/generic';
+import { newid } from './entities/newid.js';
+const KEY = Symbol.for('toa.core.instance');
+// what a queue name may carry, short enough that one made of it stays within a broker's limit
+const NAME = /^[\w.:-]{1,64}$/;
+const TIMEOUT = 5000;
+/**
+ * The name this process answers addressed calls under, and what a call to one of its stateful
+ * operations names: given by `TOA_INSTANCE`, or generated once.
+ *
+ * It is kept where every copy of this package reads it, because a binding and a component loaded
+ * against two copies must agree on whose name a call carries.
+ */
+export function instance() {
+    return (globalThis[KEY] ??= named());
+}
+/** How long an addressed call waits where it names no timeout of its own, in milliseconds. */
+export function timeout() {
+    const value = Number(environment.get('TOA_ADDRESSED_TIMEOUT'));
+    return Number.isInteger(value) && value > 0 ? value : TIMEOUT;
+}
+function named() {
+    const given = environment.get('TOA_INSTANCE');
+    if (given === undefined)
+        return newid();
+    if (!NAME.test(given))
+        throw new Error(`TOA_INSTANCE '${given}' must be 1 to 64 letters, digits, '_', '-', '.' or ':'`);
+    return given;
+}
+//# sourceMappingURL=instance.js.map

package/transpiled/instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance.js","sourceRoot":"","sources":["../source/instance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAE3C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;AAI3C,8FAA8F;AAC9F,MAAM,IAAI,GAAG,iBAAiB,CAAA;AAE9B,MAAM,OAAO,GAAG,IAAI,CAAA;AAEpB;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,CAAE,UAAoB,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC,CAAA;AACjD,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,OAAO;IACrB,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAA;IAE9D,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAA;AAC/D,CAAC;AAED,SAAS,KAAK;IACZ,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IAE7C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,EAAE,CAAA;IAEvC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,iBAAiB,KAAK,yDAAyD,CAChF,CAAA;IAEH,OAAO,KAAK,CAAA;AACd,CAAC"}

package/transpiled/locator.d.ts

@@ -0,0 +1,12 @@
+/** Where a component is, as every name derived from it. */
+export declare class Locator {
+    readonly name: string;
+    readonly namespace: string | undefined;
+    readonly id: string;
+    readonly label: string;
+    readonly uppercase: string;
+    readonly lowercase: string;
+    constructor(name: string, namespace?: string);
+    static parse(string: string): Locator;
+    hostname(prefix?: string): string;
+}

package/transpiled/locator.js

@@ -0,0 +1,32 @@
+import { concat } from '@toa.io/generic';
+/** Where a component is, as every name derived from it. */
+export class Locator {
+    name;
+    namespace;
+    id;
+    label;
+    uppercase;
+    lowercase;
+    constructor(name, namespace) {
+        if (name === undefined)
+            throw new TypeError('Locator name must be defined');
+        this.name = name;
+        this.namespace = namespace;
+        this.id = concat(namespace, '.') + name;
+        this.label = (concat(namespace, '-') + name).toLowerCase();
+        this.uppercase = (concat(namespace, '_') + name).toUpperCase();
+        this.lowercase = (concat(namespace, '_') + name).toLowerCase();
+    }
+    static parse(string) {
+        const [namespace, name] = string.split(DOT);
+        if (name === undefined)
+            return new Locator(namespace);
+        else
+            return new Locator(name, namespace);
+    }
+    hostname(prefix) {
+        return concat(prefix?.toLowerCase(), '-') + this.label;
+    }
+}
+const DOT = '.';
+//# sourceMappingURL=locator.js.map

package/transpiled/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../source/locator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAExC,2DAA2D;AAC3D,MAAM,OAAO,OAAO;IACF,IAAI,CAAQ;IACZ,SAAS,CAAoB;IAE7B,EAAE,CAAQ;IACV,KAAK,CAAQ;IACb,SAAS,CAAQ;IACjB,SAAS,CAAQ;IAEjC,YAAmB,IAAY,EAAE,SAAkB;QACjD,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAA;QAE3E,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAE1B,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;QACvC,IAAI,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAA;QAC1D,IAAI,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAA;QAC9D,IAAI,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAA;IAChE,CAAC;IAEM,MAAM,CAAC,KAAK,CAAC,MAAc;QAChC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAE3C,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC,CAAA;;YAChD,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;IAC1C,CAAC;IAEM,QAAQ,CAAC,MAAe;QAC7B,OAAO,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAA;IACxD,CAAC;CACF;AAED,MAAM,GAAG,GAAG,GAAG,CAAA"}

package/transpiled/measurements.d.ts

@@ -0,0 +1,20 @@
+/** Prometheus' own ladder, in seconds: from five milliseconds to ten seconds. */
+export declare const DURATIONS: number[];
+export declare const operation: {
+    duration: import("openspan").Histogram;
+    /** a refusal the operation chose: the operation working */
+    errors: import("openspan").Counter;
+    /** a failure nobody chose; `outcome` says whether another attempt could pass */
+    exceptions: import("openspan").Counter;
+    inflight: import("openspan").Gauge;
+};
+export declare const call: {
+    duration: import("openspan").Histogram;
+    /** only what the transmission raised: what the callee sent back is counted where it happened */
+    exceptions: import("openspan").Counter;
+    /** callers waiting, which is held for the whole round trip and not only while one runs */
+    inflight: import("openspan").Gauge;
+};
+export declare const event: {
+    publish: import("openspan").Histogram;
+};

package/transpiled/measurements.js

@@ -0,0 +1,40 @@
+import { registry } from 'openspan';
+/**
+ * What core measures, declared once for the process.
+ *
+ * An invocation and a call are two metrics rather than one with a `kind` label: a `Remote` is a
+ * `Component` too and names the very endpoint the callee does, so a single name would hold two
+ * quantities — the callee's own work, and the caller's round trip with the transport in it — and
+ * would count every remote call twice, once in each process.
+ */
+const meters = registry();
+const COMPONENT = { component: null };
+const ENDPOINT = { component: null, operation: null };
+/** Prometheus' own ladder, in seconds: from five milliseconds to ten seconds. */
+export const DURATIONS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+export const operation = {
+    duration: meters.histogram('toa.operation.duration', { buckets: DURATIONS, unit: 's' }, ENDPOINT),
+    /** a refusal the operation chose: the operation working */
+    errors: meters.counter('toa.operation.errors', {
+        ...ENDPOINT,
+        code: null
+    }),
+    /** a failure nobody chose; `outcome` says whether another attempt could pass */
+    exceptions: meters.counter('toa.operation.exceptions', {
+        ...ENDPOINT,
+        code: null,
+        outcome: null
+    }),
+    inflight: meters.gauge('toa.operation.inflight', COMPONENT)
+};
+export const call = {
+    duration: meters.histogram('toa.call.duration', { buckets: DURATIONS, unit: 's' }, ENDPOINT),
+    /** only what the transmission raised: what the callee sent back is counted where it happened */
+    exceptions: meters.counter('toa.call.exceptions', { ...ENDPOINT, code: null }),
+    /** callers waiting, which is held for the whole round trip and not only while one runs */
+    inflight: meters.gauge('toa.call.inflight', COMPONENT)
+};
+export const event = {
+    publish: meters.histogram('toa.event.publish.duration', { buckets: DURATIONS, unit: 's' }, { event: null })
+};
+//# sourceMappingURL=measurements.js.map

package/transpiled/measurements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measurements.js","sourceRoot":"","sources":["../source/measurements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAA;AAEzB,MAAM,SAAS,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAA;AACrC,MAAM,QAAQ,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAA;AAErD,iFAAiF;AACjF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;AAElF,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC,SAAS,CACxB,wBAAwB,EACxB,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,EACjC,QAAQ,CACT;IAED,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,sBAAsB,EAAE;QAC7C,GAAG,QAAQ;QACX,IAAI,EAAE,IAAI;KACX,CAAC;IAEF,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,0BAA0B,EAAE;QACrD,GAAG,QAAQ;QACX,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,IAAI;KACd,CAAC;IAEF,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE,SAAS,CAAC;CAC5D,CAAA;AAED,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,QAAQ,EAAE,MAAM,CAAC,SAAS,CACxB,mBAAmB,EACnB,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,EACjC,QAAQ,CACT;IAED,gGAAgG;IAChG,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAE9E,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,mBAAmB,EAAE,SAAS,CAAC;CACvD,CAAA;AAED,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,OAAO,EAAE,MAAM,CAAC,SAAS,CACvB,4BAA4B,EAC5B,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,EACjC,EAAE,KAAK,EAAE,IAAI,EAAE,CAChB;CACF,CAAA"}

package/transpiled/observation.d.ts

@@ -0,0 +1,7 @@
+import { Operation } from './operation.ts';
+import type { Store } from './operation.ts';
+export declare class Observation extends Operation {
+    /** an observation answers what it read, and writes none of it back */
+    protected projects: boolean;
+    protected run(store: Store): Promise<void>;
+}

package/transpiled/observation.js

@@ -0,0 +1,14 @@
+import { Operation } from './operation.js';
+export class Observation extends Operation {
+    /** an observation answers what it read, and writes none of it back */
+    projects = true;
+    async run(store) {
+        const scope = store.scope;
+        if (scope === null ||
+            (scope?.deleted === true && store.request.query?.options?.deleted !== true))
+            store.reply = null;
+        else
+            await super.run(store);
+    }
+}
+//# sourceMappingURL=observation.js.map

package/transpiled/observation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.js","sourceRoot":"","sources":["../source/observation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAI1C,MAAM,OAAO,WAAY,SAAQ,SAAS;IACxC,sEAAsE;IACnD,QAAQ,GAAY,IAAI,CAAA;IAExB,KAAK,CAAC,GAAG,CAAC,KAAY;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAsB,CAAA;QAE1C,IACE,KAAK,KAAK,IAAI;YACd,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,IAAK,KAAK,CAAC,OAAO,CAAC,KAAa,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;YAEpF,KAAK,CAAC,KAAK,GAAG,IAAI,CAAA;;YACf,MAAM,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;CACF"}

package/transpiled/operation.d.ts

@@ -0,0 +1,69 @@
+import { Readable } from 'node:stream';
+import { Connector } from './connector.ts';
+import type { Cascade } from './cascade.ts';
+import type { State } from './state.ts';
+import type { Query as Translator } from './query.ts';
+import type { Contract } from './contract/contract.ts';
+import type { Entity } from './entities/entity.ts';
+import type { EntitySet } from './entities/set.ts';
+import type { Changeset } from './entities/changeset.ts';
+import type { scope as Scope } from './types/operations.ts';
+import type { Call } from './types/inbox.ts';
+import type { Envelope, Query } from './types/request.ts';
+/** What an operation acquires for the algorithm to run against. */
+export type Scoped = Entity | EntitySet | Changeset | Readable | null;
+/** What one invocation carries from step to step. */
+export interface Store {
+    request: Envelope;
+    scope?: Scoped;
+    state?: any;
+    reply?: any;
+    /** set by a transition, which is the only operation that runs its steps again */
+    retry?: () => Promise<any>;
+}
+export interface Contracts {
+    request: Contract;
+    reply: Contract;
+}
+export interface Definition {
+    scope: Scope;
+    concurrency?: string;
+    /** whether the same call arriving twice changes state once; see `documentation/inbox.md` */
+    once?: boolean;
+}
+export declare class Operation extends Connector {
+    #private;
+    scope: State;
+    /**
+     * Whether what this operation acquires may be modified and committed. Only a
+     * transition commits, and only a commit needs the pre-image an entity keeps
+     * to diff the new state against.
+     *
+     * @protected
+     */
+    protected mutable: boolean;
+    /** whether a query of this operation may name the properties its storage reads */
+    protected projects: boolean;
+    constructor(cascade: Cascade, scope: State, contracts: Contracts, query: Translator, definition: Definition);
+    invoke(request: Envelope): Promise<any>;
+    /**
+     * The call, once. What it answered is recorded with what it changed, in one transaction, so a
+     * second arrival of the same identity finds the key taken, changes nothing, and is answered
+     * with what the first one answered.
+     *
+     * The read in front of it is not what makes that true — the key is — but it is what keeps the
+     * ordinary duplicate from running the algorithm at all, and the ordinary duplicate is a
+     * retransmission that arrives after the first call has finished.
+     */
+    protected once(store: Store): Promise<any>;
+    /**
+     * What is recorded with the write. Read where the write is made, which is after the algorithm
+     * has run, because the reply is what a duplicate is answered with.
+     */
+    protected call(store: Store): Call | undefined;
+    protected process(store: Store): Promise<any>;
+    protected acquire(store: Store): Promise<void>;
+    protected run(store: Store): Promise<void>;
+    protected commit(_store: Store): Promise<void>;
+    protected query(query?: Query): Promise<Scoped>;
+}

package/transpiled/operation.js

@@ -0,0 +1,174 @@
+import { Readable } from 'node:stream';
+import { Connector } from './connector.js';
+import { codes, SystemException, RequestContractException } from './exceptions.js';
+import { environment } from '@toa.io/generic';
+export class Operation extends Connector {
+    scope;
+    /**
+     * Whether what this operation acquires may be modified and committed. Only a
+     * transition commits, and only a commit needs the pre-image an entity keeps
+     * to diff the new state against.
+     *
+     * @protected
+     */
+    mutable = false;
+    /** whether a query of this operation may name the properties its storage reads */
+    projects = false;
+    #cascade;
+    #contracts;
+    #query;
+    #scope;
+    #once;
+    /** a reply is validated only on local environments, which are set before an operation is built */
+    #local;
+    // eslint-disable-next-line max-params
+    constructor(cascade, scope, contracts, query, definition) {
+        super();
+        this.scope = scope;
+        this.#cascade = cascade;
+        this.#contracts = contracts;
+        this.#query = query;
+        this.#scope = definition.scope;
+        this.#once = definition.once === true;
+        this.#local = environment.get('TOA_ENV') === 'local';
+        this.depends(cascade);
+    }
+    async invoke(request) {
+        try {
+            /*
+             * A projection is what a storage reads, and only an observation's read is never written
+             * back: a transition replaces the record it read, an assignment's event carries the record
+             * it changed, and an effect reads for what it does next. Refused here rather than by the
+             * contract alone, because an authentic request skips the contract.
+             */
+            if (!this.projects && request.query?.projection !== undefined)
+                throw new RequestContractException('`projection` is read by an observation alone');
+            if (request.authentic !== true)
+                this.#contracts.request.fit(request);
+            // the request carries the query onward in its parsed form: what a storage is given,
+            // not what the caller sent
+            if ('query' in request)
+                request.query = this.#query.parse(request.query);
+            // validate entity
+            if ('entity' in request)
+                this.scope.fit(request.entity);
+            const store = { request };
+            const reply = this.#once ? await this.once(store) : await this.process(store);
+            return restrict(reply, request.output);
+        }
+        catch (e) {
+            const exception = e instanceof Error ? new SystemException(e) : e;
+            return { exception };
+        }
+    }
+    /**
+     * The call, once. What it answered is recorded with what it changed, in one transaction, so a
+     * second arrival of the same identity finds the key taken, changes nothing, and is answered
+     * with what the first one answered.
+     *
+     * The read in front of it is not what makes that true — the key is — but it is what keeps the
+     * ordinary duplicate from running the algorithm at all, and the ordinary duplicate is a
+     * retransmission that arrives after the first call has finished.
+     */
+    async once(store) {
+        const { id } = store.request;
+        if (id === undefined)
+            throw new RequestContractException('a request to an operation declared `once` carries no id');
+        const recalled = await this.scope.recall(id);
+        if (recalled !== null)
+            return recalled;
+        try {
+            return await this.process(store);
+        }
+        catch (exception) {
+            if (exception?.code !== codes.DuplicateCall)
+                throw exception;
+            /*
+             * It was made between the read and the write — a duplicate that arrived while the first
+             * was still running, and lost. Nothing of this one was committed, so what is answered is
+             * the other one's reply. Absent only if the record expired in between, which is the
+             * window closing on a call nobody is waiting on any more.
+             */
+            return (await this.scope.recall(id)) ?? { exception };
+        }
+    }
+    /**
+     * What is recorded with the write. Read where the write is made, which is after the algorithm
+     * has run, because the reply is what a duplicate is answered with.
+     */
+    call(store) {
+        if (!this.#once)
+            return undefined;
+        /*
+         * A copy: an assignment fills its output in after the write it is recorded by returns, and
+         * what is recorded must be what was known when the record was made rather than whatever the
+         * reply became afterwards.
+         */
+        return { id: store.request.id, reply: { ...store.reply } };
+    }
+    async process(store) {
+        await this.acquire(store);
+        await this.run(store);
+        await this.commit(store);
+        return store.reply;
+    }
+    async acquire(store) {
+        if (this.#scope === 'none')
+            return;
+        const scope = await this.query(store.request.query);
+        const raw = scope === null || scope instanceof Readable;
+        store.scope = scope;
+        store.state = raw ? scope : scope.get();
+    }
+    async run(store) {
+        const { request, state } = store;
+        const reply = await this.#cascade.run(request.input, state);
+        if (this.#local && !(reply instanceof Readable))
+            this.#contracts.reply.fit(reply);
+        store.reply = reply;
+    }
+    async commit(_store) { }
+    async query(query) {
+        if (query === undefined)
+            throw new RequestContractException('Request query is required');
+        const acquire = this.scope[this.#scope];
+        return acquire.call(this.scope, query, this.mutable);
+    }
+}
+/**
+ * What a caller receives of the output it asked for: each object of it keeps the properties the
+ * request named, in the order the object holds them, and an empty list leaves no output at all.
+ * A system property is one of them: a caller that reads `VERSION` asks for it. A stream, an error,
+ * an exception and a value that is not an object are answered as they are.
+ */
+function restrict(reply, output) {
+    if (output === undefined || reply === null || typeof reply !== 'object')
+        return reply;
+    const answered = reply.output;
+    if (answered === undefined || answered === null || answered instanceof Readable)
+        return reply;
+    if (typeof answered !== 'object') {
+        if (output.length === 0)
+            delete reply.output;
+        return reply;
+    }
+    if (output.length === 0) {
+        delete reply.output;
+        return reply;
+    }
+    const allowed = new Set(output);
+    reply.output = Array.isArray(answered)
+        ? answered.map((entity) => entity !== null && typeof entity === 'object' ? fit(entity, allowed) : entity)
+        : fit(answered, allowed);
+    return reply;
+}
+/** Runs per entity of a collection, hence the set and the absence of intermediates. */
+function fit(entity, allowed) {
+    const output = {};
+    // the entity's own keys, so that what is answered keeps the order it was built in
+    for (const key of Object.keys(entity))
+        if (allowed.has(key))
+            output[key] = entity[key];
+    return output;
+}
+//# sourceMappingURL=operation.js.map

package/transpiled/operation.js.map

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

package/transpiled/outbox.d.ts

@@ -0,0 +1,45 @@
+import { Connector } from './connector.ts';
+import type { Atom } from './types/atomicity.ts';
+import type { Storage } from './types/storages.ts';
+import type { Destination, Row } from './types/outbox.ts';
+import type { Event } from './types/state.ts';
+export interface Options {
+    interval?: number;
+    batch?: number;
+    gap?: number;
+}
+/**
+ * Owns the intent to publish. A row is built before the write so that the storage can commit
+ * it in the same transaction as the entity; publication then happens off the operation's path,
+ * and anything that fails to publish is recovered from the row.
+ *
+ * The mechanism is a safety net: in a healthy system the row is written, published within
+ * milliseconds by the same process, and marked published on that process's next tick.
+ *
+ * A storage that cannot commit a row atomically has no outbox, and this degrades to the
+ * inline emission it replaces.
+ */
+export declare class Outbox extends Connector {
+    #private;
+    constructor(destinations: Destination[], storage: Storage | undefined, atom: Atom, options?: Options);
+    /** whether the storage can commit a row atomically with the entity */
+    get durable(): boolean;
+    /**
+     * An assignment's images are the write's own, so it hands over an event with neither, and
+     * the storage fills them in.
+     */
+    row(event: Partial<Event>): Row;
+    /**
+     * Hands a committed row over. Awaited by the caller only on the legacy path — with an
+     * outbox this returns at once and the broker leaves the operation's path.
+     */
+    publish(row: Row): Promise<void> | void;
+    protected open(): Promise<void>;
+    protected close(): Promise<void>;
+}
+/**
+ * Constant, never configuration: rows carry their lane, so lowering this would leave rows in
+ * lanes nobody reads any more. It is also the ceiling on replicas of one component, and a
+ * power of two so that the common replica counts divide evenly.
+ */
+export declare const LANES = 128;