@getaster/data 0.0.0-stage → 0.1.0-preview.0

package/dist/selection/selection.js

@@ -0,0 +1,137 @@
+import { computed, signal } from "@preact/signals-core";
+/** Cross-field policy validation shared with declarative configuration contracts. */
+export function selectionOptionsError(options) {
+    if (options.ordered && !options.multiple)
+        return "ordered selection requires multiple: true";
+    if (options.maxOrdered !== undefined && (!options.ordered || !Number.isSafeInteger(options.maxOrdered) || options.maxOrdered < 1))
+        return "maxOrdered requires ordered selection and a positive safe integer";
+    return undefined;
+}
+const NONE = new Set();
+/**
+ * The keys selected in a collection. `keys` is derived, never written back:
+ * chosen keys that have left the collection drop out, and the fallback
+ * applies, as soon as the collection changes. A key on a page the collection
+ * has unloaded stays selected.
+ */
+export class Selection {
+    #chosen = signal([]);
+    #collection;
+    multiple;
+    ordered;
+    maxOrdered;
+    keys;
+    /** The first selected key. */
+    key;
+    /** The selected records, live from the store. */
+    records;
+    /** The first selected record. */
+    selected;
+    /** The fields hidden on the first selected record (`StoredRecord.hidden`). */
+    hidden;
+    count;
+    any;
+    many;
+    constructor(store, collection, options = {}) {
+        this.#collection = "query" in collection ? signal(collection) : collection;
+        this.multiple = options.multiple ?? false;
+        this.ordered = options.ordered ?? false;
+        this.maxOrdered = options.maxOrdered;
+        const policyError = selectionOptionsError(options);
+        if (policyError)
+            throw new Error(policyError);
+        const fallback = options.fallback ?? !this.multiple;
+        // Seen keys survive eviction and ordering/projection changes. A changed
+        // membership query must show a key again before it can survive eviction.
+        let seenFor;
+        const seen = new Set();
+        this.keys = computed(() => {
+            const c = this.#collection.value;
+            const chosen = this.#chosen.value;
+            if (c.count.value === undefined)
+                return chosen;
+            if (seenFor !== c.query) {
+                const sameMembership = seenFor?.set === c.query.set && JSON.stringify(seenFor.filter) === JSON.stringify(c.query.filter);
+                seenFor = c.query;
+                if (!sameMembership)
+                    seen.clear();
+            }
+            const loaded = new Set(c.keys.value);
+            const complete = c.complete.value;
+            const kept = chosen.filter((k) => {
+                if (loaded.has(k)) {
+                    seen.add(k);
+                    return true;
+                }
+                return !complete && seen.has(k) && store.record(c.query.set, k).value !== undefined && c.has(k) !== false;
+            });
+            if (kept.length > 0 || !fallback)
+                return kept.length === chosen.length ? chosen : kept;
+            const first = c.keys.value.find((k) => k !== undefined);
+            return first === undefined ? [] : [first];
+        });
+        this.key = computed(() => this.keys.value[0]);
+        this.records = computed(() => {
+            const set = this.#collection.value.query.set;
+            const out = [];
+            for (const k of this.keys.value) {
+                const entity = store.record(set, k).value?.entity;
+                if (entity)
+                    out.push(entity);
+            }
+            return out;
+        });
+        this.selected = computed(() => this.records.value[0]);
+        this.hidden = computed(() => {
+            const k = this.key.value;
+            return (k === undefined ? undefined : store.record(this.#collection.value.query.set, k).value?.hidden) ?? NONE;
+        });
+        this.count = computed(() => this.keys.value.length);
+        this.any = computed(() => this.count.value > 0);
+        this.many = computed(() => this.count.value > 1);
+    }
+    /** The collection selected in; a signal read, so views follow a selection whose collection changes. */
+    get collection() {
+        return this.#collection.value;
+    }
+    /** Selects only `key`, or nothing. */
+    select(key) {
+        this.#chosen.value = key === undefined ? [] : [key];
+    }
+    /** Adds or removes `key` (multiple selection), or selects it alone. */
+    toggle(key) {
+        const chosen = this.keys.peek();
+        if (!this.multiple)
+            this.#chosen.value = [key];
+        else if (chosen.includes(key))
+            this.#chosen.value = chosen.filter((k) => k !== key);
+        else {
+            if (this.maxOrdered !== undefined && chosen.length >= this.maxOrdered)
+                return false;
+            this.#chosen.value = [...chosen, key];
+        }
+        return true;
+    }
+    selectAll(keys) {
+        const unique = [...new Set(keys)];
+        const next = this.multiple ? unique : unique.slice(0, 1);
+        if (this.maxOrdered !== undefined && next.length > this.maxOrdered)
+            return false;
+        this.#chosen.value = next;
+        return true;
+    }
+    /** Moves a selected key to a zero-based position; never changes membership. */
+    move(key, index) {
+        const chosen = this.keys.peek();
+        if (!this.ordered || !chosen.includes(key) || !Number.isInteger(index) || index < 0 || index >= chosen.length)
+            return false;
+        const next = chosen.filter((k) => k !== key);
+        next.splice(index, 0, key);
+        this.#chosen.value = next;
+        return true;
+    }
+    /** Selects nothing; with the fallback, the first row is selected again. */
+    clear() {
+        this.#chosen.value = [];
+    }
+}

package/dist/store/keys.d.ts

@@ -0,0 +1,10 @@
+import type { Entity, EntityType, Value } from "../schema/model.ts";
+/** Key values in key order. */
+export type KeyValues = readonly Value[];
+/** A key as a map key: equal keys always give the same text. */
+export type KeyText = string;
+export declare function keyValues(type: EntityType, entity: Entity): KeyValues;
+export declare function keyText(key: KeyValues): KeyText;
+export declare function keyOf(type: EntityType, entity: Entity): KeyText;
+export declare function hasKey(type: EntityType, entity: Entity): boolean;
+export declare function keyFromText(text: KeyText): KeyValues;

package/dist/store/keys.js

@@ -0,0 +1,21 @@
+export function keyValues(type, entity) {
+    return type.key.map((name) => {
+        const v = entity[name];
+        if (v === undefined || v === null) {
+            throw new Error(`${type.name} has no value for key property ${name}`);
+        }
+        return v;
+    });
+}
+export function keyText(key) {
+    return JSON.stringify(key);
+}
+export function keyOf(type, entity) {
+    return keyText(keyValues(type, entity));
+}
+export function hasKey(type, entity) {
+    return type.key.every((name) => entity[name] !== undefined && entity[name] !== null);
+}
+export function keyFromText(text) {
+    return JSON.parse(text);
+}

package/dist/store/store.d.ts

@@ -0,0 +1,72 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import type { Entity, Schema } from "../schema/model.ts";
+import { type KeyText } from "./keys.ts";
+export interface StoredRecord {
+    readonly entity: Entity;
+    /** Absent when the set has no `Core.OptimisticConcurrency`. */
+    readonly etag?: string;
+    /**
+     * The fields known to be current, when the record came from a `$select`
+     * and other fields may be missing or from an older version. Absent when
+     * every field is current.
+     */
+    readonly known?: ReadonlySet<string>;
+    /**
+     * Fields the server hides from this caller on this record
+     * (`@AsterData.Hidden`). Their value is `null`, which means "not yours to
+     * see", not empty.
+     *
+     * Invariant: a hidden field is never in `known`, and a record with hidden
+     * fields always has `known`. So everything that decides on a field only
+     * when it's known (a collection placing a record, page rules) treats a
+     * hidden one as unknown, and edit models never offer or send it.
+     */
+    readonly hidden?: ReadonlySet<string>;
+}
+/**
+ * Where a change came from. Sync treats them alike except that a collection
+ * never re-places a record it fetched itself: the server already put it there.
+ */
+export type Origin = {
+    readonly kind: "fetch";
+    readonly collection?: object;
+} | {
+    readonly kind: "save";
+    readonly by?: object;
+} | {
+    readonly kind: "external";
+};
+export interface StoreChange {
+    readonly set: string;
+    readonly key: KeyText;
+    readonly before: StoredRecord | undefined;
+    readonly after: StoredRecord | undefined;
+    readonly origin: Origin;
+}
+export type StoreListener = (change: StoreChange) => void;
+/**
+ * One normalized copy of every record the client holds, by set and key.
+ *
+ * Invariant: a record's signal and the listeners hear of a change in one
+ * batch, so collections have placed or removed the record before any view
+ * reads either.
+ */
+export declare class RecordStore {
+    #private;
+    constructor(schema: Schema);
+    get schema(): Schema;
+    /** A signal for the record; `undefined` until it's loaded, and after it's removed. */
+    record(set: string, key: KeyText): ReadonlySignal<StoredRecord | undefined>;
+    get(set: string, key: KeyText): StoredRecord | undefined;
+    /**
+     * Stores the record. With `fields` (a `$select`), the record holds only
+     * those fields and is merged into the stored one, never blanking the rest.
+     * No change is reported when values, ETag and known fields are unchanged.
+     */
+    put(set: string, record: StoredRecord, origin: Origin, fields?: readonly string[]): KeyText;
+    /** Stores many records, reporting changes after all are in place. */
+    putAll(set: string, records: readonly StoredRecord[], origin: Origin, fields?: readonly string[]): KeyText[];
+    remove(set: string, key: KeyText, origin: Origin): void;
+    subscribe(listener: StoreListener): () => void;
+}
+export declare function sameEntity(a: Entity, b: Entity): boolean;

package/dist/store/store.js

@@ -0,0 +1,143 @@
+import { batch, signal } from "@preact/signals-core";
+import { keyOf } from "./keys.js";
+/**
+ * One normalized copy of every record the client holds, by set and key.
+ *
+ * Invariant: a record's signal and the listeners hear of a change in one
+ * batch, so collections have placed or removed the record before any view
+ * reads either.
+ */
+export class RecordStore {
+    #schema;
+    #sets = new Map();
+    #listeners = new Set();
+    constructor(schema) {
+        this.#schema = schema;
+    }
+    get schema() {
+        return this.#schema;
+    }
+    /** A signal for the record; `undefined` until it's loaded, and after it's removed. */
+    record(set, key) {
+        return this.#slot(set, key);
+    }
+    get(set, key) {
+        return this.#sets.get(set)?.get(key)?.peek();
+    }
+    /**
+     * Stores the record. With `fields` (a `$select`), the record holds only
+     * those fields and is merged into the stored one, never blanking the rest.
+     * No change is reported when values, ETag and known fields are unchanged.
+     */
+    put(set, record, origin, fields) {
+        const type = this.#schema.set(set).type;
+        const key = keyOf(type, record.entity);
+        const slot = this.#slot(set, key);
+        const before = slot.peek();
+        const merged = fields ? partial(type, before, record, fields) : whole(type, record);
+        if (before &&
+            before.etag === merged.etag &&
+            sameEntity(before.entity, merged.entity) &&
+            sameSet(before.known, merged.known) &&
+            sameSet(before.hidden, merged.hidden)) {
+            return key;
+        }
+        const after = Object.freeze({
+            entity: Object.freeze({ ...merged.entity }),
+            ...etagOf(merged),
+            ...(merged.known ? { known: merged.known } : {}),
+            ...(merged.hidden ? { hidden: merged.hidden } : {}),
+        });
+        batch(() => {
+            slot.value = after;
+            this.#emit({ set, key, before, after, origin });
+        });
+        return key;
+    }
+    /** Stores many records, reporting changes after all are in place. */
+    putAll(set, records, origin, fields) {
+        return batch(() => records.map((r) => this.put(set, r, origin, fields)));
+    }
+    remove(set, key, origin) {
+        const slot = this.#sets.get(set)?.get(key);
+        const before = slot?.peek();
+        if (!slot || !before)
+            return;
+        batch(() => {
+            slot.value = undefined;
+            this.#emit({ set, key, before, after: undefined, origin });
+        });
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    #slot(set, key) {
+        let records = this.#sets.get(set);
+        if (!records) {
+            this.#schema.set(set);
+            records = new Map();
+            this.#sets.set(set, records);
+        }
+        let slot = records.get(key);
+        if (!slot) {
+            slot = signal(undefined);
+            records.set(key, slot);
+        }
+        return slot;
+    }
+    #emit(change) {
+        for (const listener of this.#listeners)
+            listener(change);
+    }
+}
+/** A whole record: every field current except the hidden ones. */
+function whole(type, record) {
+    const hidden = record.hidden;
+    if (!hidden?.size)
+        return { entity: record.entity, ...etagOf(record) };
+    const known = new Set(type.fields.map((f) => f.name).filter((f) => !hidden.has(f)));
+    return { entity: blanked(record.entity, hidden), ...etagOf(record), known, hidden };
+}
+/**
+ * A `$select` result merged over the stored record. The stored fields stay;
+ * they're current only when the ETag is the same version. Without ETags
+ * there are no versions to tell apart, so stored fields count as current.
+ * The fields the result carries say whether they're hidden; the others stay
+ * as last heard.
+ */
+function partial(type, before, record, fields) {
+    const hidden = new Set([...(before?.hidden ?? [])].filter((f) => !fields.includes(f)));
+    for (const f of record.hidden ?? [])
+        hidden.add(f);
+    const entity = blanked({ ...before?.entity, ...record.entity }, hidden);
+    const sameVersion = before !== undefined && before.etag === record.etag;
+    if (sameVersion && !before.known && hidden.size === 0)
+        return { entity, ...etagOf(record) };
+    const prior = sameVersion ? (before.known ?? type.fields.map((f) => f.name)) : [];
+    const known = new Set([...type.key, ...fields, ...prior]);
+    for (const f of hidden)
+        known.delete(f);
+    return { entity, ...etagOf(record), known, ...(hidden.size ? { hidden } : {}) };
+}
+/** A hidden field holds `null`, whatever an older version held. */
+function blanked(entity, hidden) {
+    if (hidden.size === 0)
+        return entity;
+    const out = { ...entity };
+    for (const f of hidden)
+        out[f] = null;
+    return out;
+}
+const etagOf = (r) => (r.etag !== undefined ? { etag: r.etag } : {});
+function sameSet(a, b) {
+    if (!a || !b)
+        return a === b;
+    return a.size === b.size && [...a].every((f) => b.has(f));
+}
+export function sameEntity(a, b) {
+    const ak = Object.keys(a);
+    if (ak.length !== Object.keys(b).length)
+        return false;
+    return ak.every((k) => Object.is(a[k], b[k]));
+}

package/dist/template/template.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Display text with values in it: `"{name} ({count == 1 ? 'one task' : count})"`.
+ * A template is parsed once, into a tree, and rendered by walking it; it's
+ * never compiled to code, so it's safe from untrusted sources and under a
+ * strict CSP. Inside braces: paths (`project.name`), string, number and
+ * boolean literals, `null`, comparisons (`== != < <= > >=`), `&&`, `||`, `!`,
+ * the conditional `a ? b : c` and parentheses. `{{` and `}}` are literal
+ * braces. A null or missing value renders as nothing.
+ */
+export interface Template {
+    readonly source: string;
+    /** The paths it reads, for following them. */
+    readonly paths: readonly string[];
+    render(lookup: (path: string) => unknown): string;
+}
+export declare class TemplateError extends Error {
+    constructor(message: string, source: string, at: number);
+}
+export declare function parseTemplate(source: string): Template;

package/dist/template/template.js

@@ -0,0 +1,186 @@
+export class TemplateError extends Error {
+    constructor(message, source, at) {
+        super(`${message} at ${at} in ${JSON.stringify(source)}`);
+        this.name = "TemplateError";
+    }
+}
+const TOKEN = /\s*(?:(\d+(?:\.\d+)?)|('(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*")|([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*)|(==|!=|<=|>=|&&|\|\||[<>!?:()]))/y;
+export function parseTemplate(source) {
+    const parts = [];
+    const paths = new Set();
+    let text = "";
+    for (let i = 0; i < source.length;) {
+        const ch = source[i];
+        if ((ch === "{" || ch === "}") && source[i + 1] === ch) {
+            text += ch;
+            i += 2;
+        }
+        else if (ch === "}") {
+            throw new TemplateError("a '}' with no '{'", source, i);
+        }
+        else if (ch !== "{") {
+            text += ch;
+            i++;
+        }
+        else {
+            if (text)
+                parts.push(text);
+            text = "";
+            const end = source.indexOf("}", i);
+            if (end < 0)
+                throw new TemplateError("a '{' with no '}'", source, i);
+            parts.push(parseExpr(source, tokenize(source, i + 1, end), end, paths));
+            i = end + 1;
+        }
+    }
+    if (text)
+        parts.push(text);
+    return {
+        source,
+        paths: [...paths],
+        render: (lookup) => parts.map((p) => (typeof p === "string" ? p : show(evaluate(p, lookup)))).join(""),
+    };
+}
+function tokenize(source, start, end) {
+    const tokens = [];
+    TOKEN.lastIndex = start;
+    while (TOKEN.lastIndex < end && !/^\s*$/.test(source.slice(TOKEN.lastIndex, end))) {
+        const at = TOKEN.lastIndex;
+        const m = TOKEN.exec(source);
+        if (!m || TOKEN.lastIndex > end)
+            throw new TemplateError("unexpected text", source, at);
+        if (m[1])
+            tokens.push({ t: m[1], kind: "num", at });
+        else if (m[2])
+            tokens.push({ t: m[2], kind: "str", at });
+        else if (m[3])
+            tokens.push({ t: m[3], kind: "id", at });
+        else
+            tokens.push({ t: m[4], kind: "op", at });
+    }
+    return tokens;
+}
+/** Precedence, loosest first: `?:`, `||`, `&&`, comparison, `!`. */
+function parseExpr(source, tokens, end, paths) {
+    let n = 0;
+    const peek = () => tokens[n]?.t;
+    const take = (t) => {
+        const tok = tokens[n];
+        if (!tok || (t !== undefined && tok.t !== t))
+            throw new TemplateError(t ? `expected '${t}'` : "expected a value", source, tok?.at ?? end);
+        n++;
+        return tok;
+    };
+    const conditional = () => {
+        const c = or();
+        if (peek() !== "?")
+            return c;
+        take("?");
+        const a = conditional();
+        take(":");
+        return { k: "if", c, a, b: conditional() };
+    };
+    const or = () => {
+        let a = and();
+        while (peek() === "||") {
+            take();
+            a = { k: "bin", op: "||", a, b: and() };
+        }
+        return a;
+    };
+    const and = () => {
+        let a = compare();
+        while (peek() === "&&") {
+            take();
+            a = { k: "bin", op: "&&", a, b: compare() };
+        }
+        return a;
+    };
+    const compare = () => {
+        const a = unary();
+        const op = peek();
+        if (op === undefined || !["==", "!=", "<", "<=", ">", ">="].includes(op))
+            return a;
+        take();
+        return { k: "bin", op, a, b: unary() };
+    };
+    const unary = () => {
+        if (peek() !== "!")
+            return primary();
+        take();
+        return { k: "not", a: unary() };
+    };
+    const primary = () => {
+        const tok = take();
+        switch (tok.kind) {
+            case "num":
+                return { k: "lit", v: Number(tok.t) };
+            case "str":
+                return { k: "lit", v: tok.t.slice(1, -1).replace(/\\(.)/g, "$1") };
+            case "id":
+                switch (tok.t) {
+                    case "true":
+                        return { k: "lit", v: true };
+                    case "false":
+                        return { k: "lit", v: false };
+                    case "null":
+                        return { k: "lit", v: null };
+                    default:
+                        paths.add(tok.t);
+                        return { k: "path", p: tok.t };
+                }
+            case "op": {
+                if (tok.t !== "(")
+                    throw new TemplateError(`unexpected '${tok.t}'`, source, tok.at);
+                const inner = conditional();
+                take(")");
+                return inner;
+            }
+        }
+    };
+    const node = conditional();
+    if (n < tokens.length)
+        throw new TemplateError("unexpected text", source, tokens[n].at);
+    return node;
+}
+function evaluate(node, lookup) {
+    switch (node.k) {
+        case "lit":
+            return node.v;
+        case "path":
+            return lookup(node.p) ?? null;
+        case "not":
+            return !truthy(evaluate(node.a, lookup));
+        case "if":
+            return truthy(evaluate(node.c, lookup)) ? evaluate(node.a, lookup) : evaluate(node.b, lookup);
+        case "bin":
+            return binary(node.op, node.a, node.b, lookup);
+    }
+}
+function binary(op, left, right, lookup) {
+    switch (op) {
+        case "&&":
+            return truthy(evaluate(left, lookup)) && truthy(evaluate(right, lookup));
+        case "||":
+            return truthy(evaluate(left, lookup)) || truthy(evaluate(right, lookup));
+        case "==":
+            return evaluate(left, lookup) === evaluate(right, lookup);
+        case "!=":
+            return evaluate(left, lookup) !== evaluate(right, lookup);
+        default: {
+            // Ordering compares numbers with numbers and text with text; anything else is false.
+            const a = evaluate(left, lookup);
+            const b = evaluate(right, lookup);
+            if (typeof a !== typeof b || (typeof a !== "number" && typeof a !== "string"))
+                return false;
+            const [x, y] = [a, b];
+            return op === "<" ? x < y : op === "<=" ? x <= y : op === ">" ? x > y : x >= y;
+        }
+    }
+}
+function truthy(v) {
+    return v !== null && v !== undefined && v !== false && v !== "" && v !== 0;
+}
+function show(v) {
+    return v === null || v === undefined ? "" : String(v);
+}

package/dist/transport.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How the OData source reaches a service. `fetch` to a real server, or an
+ * in-process call into the mock OData service; the source can't tell which.
+ */
+export type Method = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+export interface ODataRequest {
+    readonly method: Method;
+    /**
+     * Relative to the service root, without a leading slash:
+     * `Projects?$filter=state%20eq%20'active'`, `Projects(3)`, `$metadata`.
+     * Query values are percent-encoded.
+     */
+    readonly url: string;
+    /** Header names in any case. */
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+    /** Cancels this request, including any wait for authentication. */
+    readonly signal?: AbortSignal;
+}
+export interface ODataResponse {
+    readonly status: number;
+    /** Header names lower-cased. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+export type Transport = (request: ODataRequest) => Promise<ODataResponse>;
+/** A transport over `fetch` to `serviceRoot` (no trailing slash). */
+export declare function fetchTransport(serviceRoot: string, init?: RequestInit): Transport;

package/dist/transport.js

@@ -0,0 +1,20 @@
+/** A transport over `fetch` to `serviceRoot` (no trailing slash). */
+export function fetchTransport(serviceRoot, init) {
+    return async (request) => {
+        const init2 = { ...init, method: request.method };
+        const merged = new Headers(init?.headers);
+        for (const [name, value] of Object.entries(request.headers ?? {}))
+            merged.set(name, value);
+        init2.headers = merged;
+        if (request.signal)
+            init2.signal = init?.signal ? AbortSignal.any([init.signal, request.signal]) : request.signal;
+        if (request.body !== undefined)
+            init2.body = request.body;
+        const res = await fetch(`${serviceRoot}/${request.url}`, init2);
+        const headers = {};
+        res.headers.forEach((value, name) => {
+            headers[name.toLowerCase()] = value;
+        });
+        return { status: res.status, headers, body: await res.text() };
+    };
+}