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

package/transpiled/outbox.js

@@ -0,0 +1,448 @@
+import { console } from 'openspan';
+import { Connector } from './connector.js';
+import { newid } from './entities/newid.js';
+import * as trail from './trail.js';
+import * as measure from './outbox.measurements.js';
+import { environment } from '@toa.io/generic';
+/**
+ * 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 class Outbox extends Connector {
+    #destinations;
+    #storage;
+    #atom;
+    #gap;
+    #interval;
+    #batch;
+    #defer;
+    /*
+     * Everything a destination is answerable for is held per destination, which is what keeps
+     * one from delaying another: a dead one fills its own in-flight cap and the cycle stops
+     * handing it rows, while the rest go on being published and settled.
+     */
+    /** ids this process has published, by destination, held until a cycle marks them */
+    #published = new Map();
+    /** in-flight publications, by destination, awaited (with a bound) on close */
+    #inflight = new Map();
+    /** rows this replica is publishing right now, so a cycle does not pick them up again */
+    #publishing = new Map();
+    #timer;
+    #off;
+    #pumping = false;
+    /** cycles in a row this replica has been assigned no lane */
+    #unassigned = 0;
+    #closing = false;
+    // eslint-disable-next-line max-params
+    constructor(destinations, storage, atom, options = {}) {
+        super();
+        this.#destinations = destinations;
+        this.#storage = storage;
+        this.#atom = atom;
+        for (const destination of destinations) {
+            this.#published.set(destination.name, new Set());
+            this.#inflight.set(destination.name, new Set());
+            this.#publishing.set(destination.name, new Set());
+        }
+        this.#interval = number('TOA_OUTBOX_INTERVAL', options.interval, INTERVAL);
+        this.#batch = number('TOA_OUTBOX_BATCH', options.batch, BATCH);
+        this.#gap = options.gap ?? this.#interval * K;
+        this.#defer = environment.get('TOA_OUTBOX_DEFER') === '1';
+        // one at a time: an array would link the group it makes rather than its members
+        for (const destination of destinations)
+            this.depends(destination);
+        this.depends(atom);
+        if (storage !== undefined)
+            this.depends(storage);
+    }
+    /** whether the storage can commit a row atomically with the entity */
+    get durable() {
+        return this.#storage?.outbox !== undefined;
+    }
+    /**
+     * 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) {
+        const row = {
+            id: newid(),
+            lane: this.#lane(),
+            published: false,
+            pending: Date.now() + this.#gap,
+            outstanding: this.#destinations.map((destination) => destination.name),
+            event: event
+        };
+        /*
+         * This runs on the operation's own path, which is the only moment the chain is in scope:
+         * the pump that publishes the row may be another replica, an hour later. A row that had
+         * no chain stores no field.
+         */
+        const hops = trail.current()?.hops;
+        if (hops !== undefined)
+            row.trail = hops;
+        return 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) {
+        // without a durable outbox this is the inline path, and the caller awaits every destination
+        if (!this.durable)
+            return this.#inline(row);
+        /*
+         * A publication started while the pump is closing would outlive the emitters it needs,
+         * and `comq` waits on a connection that is going rather than failing. The row is already
+         * durable, so leaving it is exactly what it is for.
+         */
+        if (this.#closing || this.#defer)
+            return;
+        this.#publish(row);
+    }
+    /**
+     * The inline path, where there is no row to come back to: every destination is attempted and
+     * the operation waits for all of them, so a failure reaches whoever wrote.
+     */
+    async #inline(row) {
+        const sending = this.#destinations
+            .filter((destination) => row.outstanding.includes(destination.name))
+            .map(async (destination) => destination.emit(row));
+        await Promise.all(sending);
+    }
+    async open() {
+        if (!this.durable)
+            return;
+        if (this.#defer)
+            console.warn('Outbox immediate publication is deferred; events are published by the pump only');
+        this.#timer = setInterval(() => {
+            this.#tick();
+        }, this.#interval);
+        this.#timer.unref();
+        /*
+         * A lane changing hands is exactly when rows stranded in it become this replica's to
+         * publish, and the cycle would not notice for up to an interval. Being told costs a cycle
+         * that finds nothing in the usual case, where the claim arrives once and never changes.
+         */
+        this.#off = this.#atom.onassigned(() => {
+            this.#tick();
+        });
+    }
+    async close() {
+        this.#closing = true;
+        this.#off?.();
+        if (this.#timer !== undefined)
+            clearInterval(this.#timer);
+        await this.#drain();
+        await this.#mark();
+    }
+    /**
+     * Publishes one row and swallows the failure: the row stays unpublished and comes back on a
+     * later cycle, which is the whole point of having written it.
+     *
+     * There is no timeout here on purpose. A publication is a confirmed write to a durable
+     * exchange, and `comq` waits for the broker to come back rather than failing — abandoning
+     * it would not stop it, it would only mean the row is published twice once it lands. What
+     * bounds this instead is the in-flight cap and the drain on close.
+     *
+     */
+    /** @returns what it started, so a cycle can wait for it before marking */
+    #publish(row) {
+        const started = [];
+        for (const destination of this.#destinations)
+            if (this.#due(row, destination.name))
+                started.push(this.#send(row, destination));
+        return started;
+    }
+    /**
+     * Whether this row is still this process's to send to that destination. A destination the
+     * row names and this process does not have is not its to send, and is left where it is.
+     */
+    #due(row, destination) {
+        if (!row.outstanding.includes(destination))
+            return false;
+        const published = this.#published.get(destination);
+        if (published === undefined)
+            return false;
+        return !published.has(row.id) && !this.#publishing.get(destination).has(row.id);
+    }
+    /**
+     * Publishes one row to one destination and swallows the failure: the row stays outstanding
+     * for it and comes back on a later cycle, which is the whole point of having written it.
+     * Nothing here reaches the other destinations of the same row.
+     *
+     * There is no timeout on purpose. A publication is a confirmed write to a durable exchange,
+     * and `comq` waits for the broker to come back rather than failing — abandoning it would not
+     * stop it, it would only mean the row is published twice once it lands. What bounds this
+     * instead is the in-flight cap, which is per destination so that a dead one cannot stop the
+     * cycle from feeding the others, and the drain on close.
+     */
+    async #send(row, destination) {
+        const name = destination.name;
+        const published = this.#published.get(name);
+        const publishing = this.#publishing.get(name);
+        const inflight = this.#inflight.get(name);
+        if (inflight.size >= INFLIGHT || published.size >= PUBLISHED)
+            return;
+        publishing.add(row.id);
+        const sending = destination.emit(row);
+        inflight.add(sending);
+        try {
+            await sending;
+            published.add(row.id);
+        }
+        catch (error) {
+            // the message, not the error: an `Error` has no enumerable own properties, so what
+            // reached the log was `{}` and a publication that keeps failing said nothing about why
+            measure.failed(name);
+            console.warn('Outbox publication failed', {
+                row: row.id,
+                destination: name,
+                message: error?.message
+            });
+        }
+        finally {
+            inflight.delete(sending);
+            publishing.delete(row.id);
+        }
+    }
+    /**
+     * `comq` retries a publish for as long as the broker is down rather than rejecting, so an
+     * unbounded drain outlives any grace period.
+     *
+     */
+    async #drain() {
+        const inflight = [...this.#inflight.values()].flatMap((set) => [...set]);
+        if (inflight.length === 0)
+            return;
+        await Promise.race([Promise.allSettled(inflight), delay(DRAIN)]);
+    }
+    /**
+     * Reads what is due, publishes it, and marks everything this process has sent — what it just
+     * published and what the immediate path published since the last cycle. One cycle at a time.
+     *
+     */
+    #tick() {
+        if (this.#pumping)
+            return;
+        this.#pumping = true;
+        void this.#pump().finally(() => (this.#pumping = false));
+    }
+    async #pump() {
+        this.#assignment();
+        let page;
+        let after;
+        // what this cycle saw, so that a destination it read nothing for is set to zero rather
+        // than left holding whatever the cycle before it found
+        const counts = new Map();
+        const oldest = new Map();
+        do {
+            page = await this.#read(after);
+            if (page.length === 0)
+                break;
+            // so a page is never read twice
+            after = page[page.length - 1]?.id;
+            /*
+             * A row is unpublished in the database until a cycle marks it, so a page includes what
+             * this replica is sending right now and what a failed marking left behind. Only this
+             * process knows either.
+             */
+            const rows = page.filter((row) => this.#destinations.some((destination) => this.#due(row, destination.name)));
+            this.#outstanding(rows, counts, oldest);
+            if (rows.length > 0) {
+                console.debug('Outbox recovering unpublished rows', { count: rows.length });
+                // every row is given its chance, at every destination it is still outstanding for;
+                // what a broker refused stays outstanding there and comes back on a later cycle
+                await this.#awaited(rows.flatMap((row) => this.#publish(row)));
+            }
+            // a full page is a page that may have been cut short
+        } while (page.length === this.#batch);
+        measure.cycled(this.#destinations.map((destination) => destination.name), counts, oldest);
+        await this.#mark();
+    }
+    /** What a page leaves outstanding, by destination: how many, and the oldest of them. */
+    #outstanding(rows, counts, oldest) {
+        for (const row of rows)
+            for (const { name } of this.#destinations) {
+                if (!this.#due(row, name))
+                    continue;
+                counts.set(name, (counts.get(name) ?? 0) + 1);
+                oldest.set(name, Math.min(oldest.get(name) ?? row.pending, row.pending));
+            }
+    }
+    /**
+     * Says when this replica has owned nothing for long enough that nothing is going to assign
+     * it anything.
+     *
+     * Owning no lane is ordinary for a moment — a replica that has just started has not been
+     * told yet — and is why nothing here refuses at boot: one cycle of it cannot be told from an
+     * atomicity that is absent. Ten in a row can, and what it means is that this outbox recovers
+     * nothing: a publication that failed is never retried, and that change is lost with the
+     * process that failed to make it.
+     *
+     * Said every ten cycles rather than once, so that it is still there to be found in a log
+     * read long after the deployment that broke it, and once when it is over.
+     */
+    #assignment() {
+        const lanes = this.#atom.slots(LANES);
+        if (lanes !== null && lanes.length > 0) {
+            if (this.#unassigned >= UNASSIGNED)
+                console.info('Outbox lanes assigned, recovery resumed');
+            this.#unassigned = 0;
+            measure.starving(0);
+            return;
+        }
+        this.#unassigned++;
+        measure.starving(this.#unassigned);
+        if (this.#unassigned % UNASSIGNED === 0)
+            console.warn('Outbox owns no lane and recovers nothing', {
+                cycles: this.#unassigned,
+                interval: this.#interval
+            });
+    }
+    /**
+     * One page of what is due. In a healthy system the first one is empty, every cycle — a row is
+     * due only if the process that wrote it failed to publish or died before marking it.
+     *
+     * Reading is suspended, not stopped, while this replica does not know which lanes are its
+     * own: the cycle keeps running and keeps marking, and reading resumes as soon as an
+     * assignment arrives. Reading without an assignment would be a different guarantee, where
+     * every replica publishes every stranded row.
+     *
+     * @param after the last id of the page before, so a page is never read twice
+     */
+    async #read(after) {
+        const lanes = this.#atom.slots(LANES);
+        if (lanes === null || lanes.length === 0)
+            return [];
+        return this.#storage.outbox.pending(lanes, Date.now(), this.#batch, after).catch((error) => {
+            console.warn('Outbox read failed', { error });
+            return [];
+        });
+    }
+    /**
+     * Waits for what this cycle started, so that it marks what it sent rather than leaving it to
+     * the next one — but not past its own interval. A publication is never abandoned: it stays in
+     * flight, `#publishing` keeps a later cycle from sending it again, and the drain on close
+     * still waits for it. What is bounded is only how long a cycle waits before marking the rest,
+     * so that one destination with nothing to say cannot hold up the settling of another.
+     */
+    async #awaited(started) {
+        if (started.length === 0)
+            return;
+        await Promise.race([Promise.allSettled(started), delay(this.#interval)]);
+    }
+    /**
+     * One batched write for many rows, which is why the ids are held in memory rather than
+     * marked one by one. Ids that fail to be marked are kept and retried; a row that is never
+     * marked is simply published again, which is within the contract.
+     *
+     * Rows are grouped by the destinations that completed for them, so the ordinary case — every
+     * destination landing in the same window — is one group and one write, as it was when there
+     * was only ever one. A second write happens where the destinations diverged, which is the
+     * failure this exists for.
+     */
+    async #mark() {
+        for (const [destinations, ids] of this.#groups())
+            await this.#settle(destinations, ids);
+    }
+    /** @private */
+    async #settle(destinations, ids) {
+        try {
+            await this.#storage.outbox.settle(ids, destinations);
+        }
+        catch (error) {
+            console.warn('Outbox marking failed', { count: ids.length, error });
+            return;
+        }
+        for (const destination of destinations) {
+            const published = this.#published.get(destination);
+            for (const id of ids)
+                published.delete(id);
+        }
+    }
+    /**
+     * What has been published since the last cycle, as rows sharing the destinations that
+     * completed for them.
+     */
+    #groups() {
+        /** the destinations that completed for an id, in the order the destinations are held */
+        const completed = new Map();
+        for (const [destination, ids] of this.#published)
+            for (const id of ids) {
+                const names = completed.get(id);
+                if (names === undefined)
+                    completed.set(id, [destination]);
+                else
+                    names.push(destination);
+            }
+        const groups = new Map();
+        for (const [id, destinations] of completed) {
+            const key = destinations.join(SEPARATOR);
+            const group = groups.get(key);
+            if (group === undefined)
+                groups.set(key, [destinations, [id]]);
+            else
+                group[1].push(id);
+        }
+        return [...groups.values()];
+    }
+    /**
+     * A lane this replica currently owns, so that in steady state it settles its own rows
+     * before it ever reads them. Any lane at all when it owns none: the row still has to be
+     * written, and whoever ends up owning that lane will pump it.
+     *
+     */
+    #lane() {
+        const owned = this.#atom.slots(LANES);
+        return owned === null || owned.length === 0
+            ? Math.floor(Math.random() * LANES)
+            : owned[Math.floor(Math.random() * owned.length)];
+    }
+}
+function number(variable, declared, fallback) {
+    if (declared !== undefined)
+        return declared;
+    const value = Number(environment.get(variable));
+    return Number.isNaN(value) || value <= 0 ? fallback : value;
+}
+async function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms).unref();
+    });
+}
+/**
+ * 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 const LANES = 128;
+/** one cycle reads, publishes and marks; in steady state it finds nothing to read */
+/**
+ * Cycles owning nothing before that is said out loud, and between one saying and the next.
+ * Long enough that a replica which has just started, or one whose assignment is being redrawn,
+ * says nothing at all.
+ */
+const UNASSIGNED = 10;
+const INTERVAL = 5000;
+/**
+ * `gap = interval * K`. Not a steady-state necessity — a replica writes into a lane it owns
+ * and marks what it published — but a guard for when a lane changes hands between the write
+ * and the settle. Two cycles of separation, plus one of margin.
+ */
+const K = 3;
+/** how many rows one read brings back; the pump reads on while a page comes back full */
+const BATCH = 200;
+const DRAIN = 10_000;
+/** publications in flight at once, per destination */
+const INFLIGHT = 1000;
+const PUBLISHED = 10_000;
+/** what a group of destinations is keyed by; no name can hold it */
+const SEPARATOR = '\u0000';
+//# sourceMappingURL=outbox.js.map

package/transpiled/outbox.js.map

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

package/transpiled/outbox.measurements.d.ts

@@ -0,0 +1,4 @@
+export declare function failed(destination: string): void;
+export declare function starving(cycles: number): void;
+/** What one cycle saw, set together so that a destination it read nothing for reads as zero. */
+export declare function cycled(destinations: string[], counts: Map<string, number>, oldest: Map<string, number>): void;

package/transpiled/outbox.measurements.js

@@ -0,0 +1,38 @@
+import { registry } from 'openspan';
+/**
+ * What the outbox measures, and the zone with the most to gain from being measured: the pump
+ * swallows a publication failure into a log line, so events stop leaving and nothing says so.
+ */
+const meters = registry();
+const DESTINATION = { destination: null };
+/** Rows this replica has read as still outstanding, at the end of a cycle. */
+const pending = meters.gauge('toa.outbox.pending', DESTINATION);
+/**
+ * How long the oldest outstanding row has waited. The number to alert on, because it is one
+ * threshold a person can choose — *events are more than N seconds behind* — where a count of rows
+ * has none: a handful four hours old is a stuck destination, a thousand a second old is a busy one.
+ */
+const age = meters.gauge('toa.outbox.age', DESTINATION);
+const failures = meters.counter('toa.outbox.failures', DESTINATION);
+/**
+ * Cycles in a row this replica was given no lane. Past ten it means this outbox recovers nothing:
+ * a publication that failed is never retried, and that change is lost with the process that failed
+ * to make it.
+ */
+const unassigned = meters.gauge('toa.outbox.unassigned');
+export function failed(destination) {
+    failures.add(1, { destination });
+}
+export function starving(cycles) {
+    unassigned.set(cycles);
+}
+/** What one cycle saw, set together so that a destination it read nothing for reads as zero. */
+export function cycled(destinations, counts, oldest) {
+    const now = Date.now();
+    for (const destination of destinations) {
+        pending.set(counts.get(destination) ?? 0, { destination });
+        const since = oldest.get(destination);
+        age.set(since === undefined ? 0 : Math.max(0, (now - since) / 1000), { destination });
+    }
+}
+//# sourceMappingURL=outbox.measurements.js.map

package/transpiled/outbox.measurements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.measurements.js","sourceRoot":"","sources":["../source/outbox.measurements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC;;;GAGG;AACH,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAA;AAEzB,MAAM,WAAW,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,CAAA;AAEzC,8EAA8E;AAC9E,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAA;AAE/D;;;;GAIG;AACH,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAA;AAEvD,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAA;AAEnE;;;;GAIG;AACH,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAA;AAExD,MAAM,UAAU,MAAM,CAAC,WAAmB;IACxC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAA;AAClC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;AACxB,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,MAAM,CACpB,YAAsB,EACtB,MAA2B,EAC3B,MAA2B;IAE3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAEtB,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAA;QAE1D,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QAErC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAA;IACvF,CAAC;AACH,CAAC"}

package/transpiled/query/criteria.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from '../types/storages.ts';
+/** What a component declares about the properties a criteria may select on. */
+export type Properties = Record<string, {
+    type: string;
+}>;
+export declare function criteria(expression: string, properties?: Properties): Node;

package/transpiled/query/criteria.js

@@ -0,0 +1,74 @@
+import { parse } from '@rsql/parser';
+import { QuerySyntaxException } from '../exceptions.js';
+export function criteria(expression, properties) {
+    let ast;
+    try {
+        ast = parse(expression);
+    }
+    catch (e) {
+        throw new QuerySyntaxException(e.message);
+    }
+    if (properties !== undefined)
+        read(ast, properties);
+    return ast;
+}
+function read(node, properties) {
+    if (node.type === 'COMPARISON' &&
+        node.left?.type === 'SELECTOR' &&
+        node.right?.type === 'VALUE') {
+        const selector = node.left.selector;
+        const property = properties[selector];
+        if (property === undefined) {
+            throw new QuerySyntaxException(`Criteria selector '${selector}' is not defined`);
+        }
+        const cast = CAST[property.type];
+        // `=in=` and `=out=` carry a list, and casting that as one value gives whatever
+        // a comma-separated string reads as
+        if (cast !== undefined)
+            node.right.value = Array.isArray(node.right.value)
+                ? node.right.value.map((value) => cast(value, selector))
+                : cast(node.right.value, selector);
+    }
+    else {
+        if (node.left !== undefined)
+            read(node.left, properties);
+        if (node.right !== undefined)
+            read(node.right, properties);
+    }
+}
+/**
+ * A criteria arrives as text, so a value is read as what the property it selects on holds. What
+ * cannot be read as that is refused rather than passed on: `parseInt` answers `NaN` for a word
+ * and `12` for `12kg`, and a storage asked to match either finds nothing and says nothing —
+ * a mistyped filter reads as an empty result.
+ *
+ * A string is left as it came, because every text is one: what a criteria may compare a string
+ * to is not the type's to say.
+ */
+const CAST = {
+    number: (value, selector) => finite(value, selector, 'a number'),
+    integer: (value, selector) => {
+        const number = finite(value, selector, 'an integer');
+        if (!Number.isInteger(number))
+            refuse(selector, 'an integer', value);
+        return number;
+    },
+    boolean: (value, selector) => {
+        if (value === 'true')
+            return true;
+        if (value === 'false')
+            return false;
+        return refuse(selector, 'a boolean', value);
+    }
+};
+function finite(value, selector, expected) {
+    // `Number` reads a blank string as zero, and a criteria that says nothing says nothing
+    const number = value.trim() === '' ? Number.NaN : Number(value);
+    if (!Number.isFinite(number))
+        refuse(selector, expected, value);
+    return number;
+}
+function refuse(selector, expected, value) {
+    throw new QuerySyntaxException(`Criteria selector '${selector}' takes ${expected}, and '${value}' is not one`);
+}
+//# sourceMappingURL=criteria.js.map

package/transpiled/query/criteria.js.map

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

package/transpiled/query/options.d.ts

@@ -0,0 +1,3 @@
+import type { Options } from '../types/storages.ts';
+import type { Properties } from './criteria.ts';
+export declare function options(given: Record<string, any>, properties: Properties): Options;

package/transpiled/query/options.js

@@ -0,0 +1,34 @@
+import { QuerySyntaxException } from '../exceptions.js';
+export function options(given, properties) {
+    if (given.sort !== undefined)
+        given.sort = sort(given.sort, properties);
+    if (given.projection !== undefined)
+        given.projection = projection(given.projection, properties);
+    return given;
+}
+function sort(sort, properties) {
+    const result = [];
+    for (const sorting of sort) {
+        const [property, direction] = sorting.split(':');
+        if (properties[property] === undefined)
+            throw new QuerySyntaxException(`Sort property '${property}' is not defined`);
+        result.push([property, direction ?? 'asc']);
+    }
+    return result;
+}
+/**
+ * A copy, because a route declares one projection and sends it with every request it serves,
+ * and the system properties are what every read answers besides.
+ */
+function projection(declared, properties) {
+    for (const property of declared)
+        if (properties[property] === undefined)
+            throw new QuerySyntaxException(`Projection property '${property}' is not defined`);
+    const projection = declared.slice();
+    for (const property of SYSTEM)
+        if (!projection.includes(property))
+            projection.push(property);
+    return projection;
+}
+const SYSTEM = ['VERSION', 'CREATED', 'UPDATED', 'DELETED', 'REGION'];
+//# sourceMappingURL=options.js.map

package/transpiled/query/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../source/query/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAIvD,MAAM,UAAU,OAAO,CAAC,KAA0B,EAAE,UAAsB;IACxE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IAEvE,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAChC,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;IAE7D,OAAO,KAAgB,CAAA;AACzB,CAAC;AAED,SAAS,IAAI,CAAC,IAAc,EAAE,UAAsB;IAClD,MAAM,MAAM,GAA4B,EAAE,CAAA;IAE1C,KAAK,MAAM,OAAO,IAAI,IAAI,EAAE,CAAC;QAC3B,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAEhD,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,SAAS;YACpC,MAAM,IAAI,oBAAoB,CAAC,kBAAkB,QAAQ,kBAAkB,CAAC,CAAA;QAE9E,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,IAAI,KAAK,CAAC,CAAC,CAAA;IAC7C,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,QAAkB,EAAE,UAAsB;IAC5D,KAAK,MAAM,QAAQ,IAAI,QAAQ;QAC7B,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,SAAS;YACpC,MAAM,IAAI,oBAAoB,CAAC,wBAAwB,QAAQ,kBAAkB,CAAC,CAAA;IAEtF,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAA;IAEnC,KAAK,MAAM,QAAQ,IAAI,MAAM;QAC3B,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAE/D,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,MAAM,MAAM,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAA"}

package/transpiled/query.d.ts

@@ -0,0 +1,9 @@
+import type { Properties } from './query/criteria.ts';
+import type { Query as Parsed } from './types/storages.ts';
+import type { Query as Requested } from './types/request.ts';
+/** Translates the query a request carries into the one a storage is given. */
+export declare class Query {
+    #private;
+    constructor(properties: Properties);
+    parse(query: Requested): Parsed;
+}