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

package/dist/criteria/values.js

@@ -0,0 +1,283 @@
+/** A criteria problem: unknown field, a value that doesn't fit its field, or a bad stored value. */
+export class CriteriaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CriteriaError";
+    }
+}
+const INT_RANGES = {
+    "Edm.Byte": [0, 255],
+    "Edm.SByte": [-128, 127],
+    "Edm.Int16": [-32768, 32767],
+    "Edm.Int32": [-2147483648, 2147483647],
+};
+const RE_INT64 = /^-?\d+$/;
+const RE_DECIMAL = /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/;
+const RE_DATE = /^(-?\d{4,})-(\d{2})-(\d{2})$/;
+const RE_TIME = /^(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,12}))?)?$/;
+const RE_DTO = /^(-?\d{4,})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,12}))?)?(?:[Zz]|([+-])(\d{2}):(\d{2}))$/;
+const RE_GUID = /^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}$/;
+const RE_DURATION = /^(-)?P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)(?:\.(\d{1,12}))?S)?)?$/;
+export function isFloatType(field) {
+    return field.type === "Edm.Single" || field.type === "Edm.Double";
+}
+/** Throws `CriteriaError` unless `value` is a legal JS value for `field`'s Edm type. */
+export function assertLiteral(value, field) {
+    if (value === null)
+        return;
+    const bad = (why) => {
+        throw new CriteriaError(`${field.name}: ${why} (${field.type}), got ${JSON.stringify(value)}`);
+    };
+    const t = field.type;
+    switch (t) {
+        case "Edm.String":
+            if (typeof value !== "string")
+                bad("expected a string");
+            return;
+        case "Edm.Boolean":
+            if (typeof value !== "boolean")
+                bad("expected a boolean");
+            return;
+        case "Edm.Byte":
+        case "Edm.SByte":
+        case "Edm.Int16":
+        case "Edm.Int32": {
+            const [lo, hi] = INT_RANGES[t];
+            if (typeof value !== "number" || !Number.isInteger(value) || value < lo || value > hi) {
+                bad("expected an integer in range");
+            }
+            return;
+        }
+        case "Edm.Single":
+        case "Edm.Double":
+            if (typeof value !== "number")
+                bad("expected a number");
+            return;
+        case "Edm.Int64":
+            if (typeof value !== "string" || !RE_INT64.test(value))
+                bad("expected an integer string");
+            return;
+        case "Edm.Decimal":
+            if (typeof value !== "string" || !RE_DECIMAL.test(value))
+                bad("expected a decimal string");
+            return;
+        case "Edm.Date":
+            if (typeof value !== "string" || !RE_DATE.test(value))
+                bad("expected YYYY-MM-DD");
+            return;
+        case "Edm.TimeOfDay":
+            if (typeof value !== "string" || !RE_TIME.test(value))
+                bad("expected hh:mm[:ss[.f]]");
+            return;
+        case "Edm.DateTimeOffset":
+            if (typeof value !== "string" || !RE_DTO.test(value))
+                bad("expected an RFC 3339 timestamp with offset");
+            return;
+        case "Edm.Guid":
+            if (typeof value !== "string" || !RE_GUID.test(value))
+                bad("expected a GUID");
+            return;
+        case "Edm.Duration":
+            if (typeof value !== "string" || !RE_DURATION.test(value) || value === "P" || value === "-P") {
+                bad("expected an ISO 8601 day-time duration");
+            }
+            return;
+        case "Edm.Binary":
+            throw new CriteriaError(`${field.name}: Edm.Binary values are not supported in criteria`);
+    }
+}
+const RE_NUM = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/;
+function parseDec(v, field) {
+    const s = typeof v === "number" ? String(v) : v;
+    const m = RE_NUM.exec(s);
+    if (!m || (m[2] === "" && (m[3] ?? "") === "")) {
+        throw new CriteriaError(`${field.name}: not a number: ${JSON.stringify(v)}`);
+    }
+    const frac = m[3] ?? "";
+    let mant = BigInt(`${m[2] || "0"}${frac}`);
+    if (m[1] === "-")
+        mant = -mant;
+    const exp = Number(m[4] ?? 0) - frac.length;
+    return exp <= 0 ? { m: mant, e: -exp } : { m: mant * 10n ** BigInt(exp), e: 0 };
+}
+function cmpDec(a, b) {
+    const e = Math.max(a.e, b.e);
+    const x = a.m * 10n ** BigInt(e - a.e);
+    const y = b.m * 10n ** BigInt(e - b.e);
+    return x < y ? -1 : x > y ? 1 : 0;
+}
+function cmpNum(a, b) {
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return undefined;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function toNumber(v, field) {
+    if (typeof v === "number")
+        return v;
+    if (typeof v === "string" && RE_NUM.test(v))
+        return Number(v);
+    throw new CriteriaError(`${field.name}: expected a number, got ${JSON.stringify(v)}`);
+}
+// ---- temporal parsing, memoised: sorting parses each value many times ----
+const memo = new Map();
+function cached(kind, s, parse) {
+    const k = `${kind}\0${s}`;
+    const hit = memo.get(k);
+    if (hit !== undefined)
+        return hit;
+    const v = parse();
+    if (memo.size >= 20000)
+        memo.clear();
+    memo.set(k, v);
+    return v;
+}
+function daysFromCivil(y, m, d) {
+    const yy = m <= 2 ? y - 1 : y;
+    const era = Math.floor(yy / 400);
+    const yoe = yy - era * 400;
+    const doy = Math.floor((153 * (m + (m > 2 ? -3 : 9)) + 2) / 5) + d - 1;
+    const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
+    return era * 146097 + doe - 719468;
+}
+function nanos(frac) {
+    return frac === undefined ? 0 : Number(frac.padEnd(12, "0").slice(0, 9));
+}
+function bad(field, v) {
+    throw new CriteriaError(`${field.name}: invalid ${field.type} value ${JSON.stringify(v)}`);
+}
+/** `[days since epoch]` for a Date. */
+function dateKey(v, field) {
+    if (typeof v !== "string")
+        return bad(field, v);
+    return cached("d", v, () => {
+        const m = RE_DATE.exec(v);
+        if (!m)
+            return bad(field, v);
+        return daysFromCivil(Number(m[1]), Number(m[2]), Number(m[3]));
+    });
+}
+function timeKey(v, field) {
+    if (typeof v !== "string")
+        return bad(field, v);
+    return cached("t", v, () => {
+        const m = RE_TIME.exec(v);
+        if (!m)
+            return bad(field, v);
+        // A leap second (:60) sorts after :59 and its fraction, as in the engine.
+        return (Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3] ?? 0)) * 1e9 + nanos(m[4]);
+    });
+}
+/** `[UTC seconds, nanoseconds]`: orders by instant, ignoring the offset. */
+function instantKey(v, field) {
+    if (typeof v !== "string")
+        return bad(field, v);
+    return cached("i", v, () => {
+        const m = RE_DTO.exec(v);
+        if (!m)
+            return bad(field, v);
+        const offset = m[8] === undefined ? 0 : (m[8] === "-" ? -1 : 1) * (Number(m[9]) * 3600 + Number(m[10]) * 60);
+        const secs = daysFromCivil(Number(m[1]), Number(m[2]), Number(m[3])) * 86400 +
+            Number(m[4]) * 3600 +
+            Number(m[5]) * 60 +
+            Number(m[6] ?? 0) -
+            offset;
+        return [secs, nanos(m[7])];
+    });
+}
+function durationKey(v, field) {
+    if (typeof v !== "string")
+        return bad(field, v);
+    return cached("u", v, () => {
+        const m = RE_DURATION.exec(v);
+        if (!m || v === "P" || v === "-P")
+            return bad(field, v);
+        let ns = BigInt(m[2] ?? 0) * 86400000000000n +
+            BigInt(m[3] ?? 0) * 3600000000000n +
+            BigInt(m[4] ?? 0) * 60000000000n +
+            BigInt(m[5] ?? 0) * 1000000000n +
+            BigInt(nanos(m[6]));
+        if (m[1] === "-")
+            ns = -ns;
+        return ns;
+    });
+}
+/** Unicode code point order: what the engine's byte-wise UTF-8 comparison gives. */
+export function compareCodePoints(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const x = a.charCodeAt(i);
+        const y = b.charCodeAt(i);
+        if (x === y)
+            continue;
+        // UTF-16 order differs from code point order only when a surrogate meets a
+        // BMP unit at or above U+E000: surrogates stand for code points >= U+10000.
+        const xs = x >= 0xd800 && x <= 0xdfff;
+        const ys = y >= 0xd800 && y <= 0xdfff;
+        if (xs !== ys)
+            return xs ? 1 : -1;
+        return x < y ? -1 : 1;
+    }
+    return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;
+}
+function sign(x) {
+    return x < 0 ? -1 : x > 0 ? 1 : 0;
+}
+/**
+ * Orders two non-null values of `field`'s type; `undefined` when unordered
+ * (a NaN is involved).
+ */
+export function ordering(a, b, field) {
+    switch (field.type) {
+        case "Edm.String":
+            if (typeof a !== "string" || typeof b !== "string")
+                return bad(field, typeof a !== "string" ? a : b);
+            return compareCodePoints(a, b);
+        case "Edm.Boolean":
+            if (typeof a !== "boolean" || typeof b !== "boolean")
+                return bad(field, typeof a !== "boolean" ? a : b);
+            return a === b ? 0 : a ? 1 : -1;
+        case "Edm.Byte":
+        case "Edm.SByte":
+        case "Edm.Int16":
+        case "Edm.Int32":
+        case "Edm.Single":
+        case "Edm.Double":
+            return cmpNum(toNumber(a, field), toNumber(b, field));
+        case "Edm.Int64":
+        case "Edm.Decimal": {
+            // A non-integer JS number is a double, which makes the comparison floating point.
+            const fa = typeof a === "number" && !Number.isInteger(a);
+            const fb = typeof b === "number" && !Number.isInteger(b);
+            if (fa || fb)
+                return cmpNum(toNumber(a, field), toNumber(b, field));
+            return cmpDec(parseDec(a, field), parseDec(b, field));
+        }
+        case "Edm.Date":
+            return sign(dateKey(a, field) - dateKey(b, field));
+        case "Edm.TimeOfDay":
+            return sign(timeKey(a, field) - timeKey(b, field));
+        case "Edm.DateTimeOffset": {
+            const [s1, n1] = instantKey(a, field);
+            const [s2, n2] = instantKey(b, field);
+            return s1 !== s2 ? sign(s1 - s2) : sign(n1 - n2);
+        }
+        case "Edm.Duration":
+            return sign(durationKey(a, field) - durationKey(b, field));
+        case "Edm.Guid":
+            if (typeof a !== "string" || typeof b !== "string")
+                return bad(field, typeof a !== "string" ? a : b);
+            return compareCodePoints(a.toLowerCase(), b.toLowerCase());
+        case "Edm.Binary":
+            throw new CriteriaError(`${field.name}: Edm.Binary values are not supported in criteria`);
+    }
+}
+/** Whether a number value is NaN (sorts after everything, equal to itself). */
+export function isNaNValue(v) {
+    return typeof v === "number" && Number.isNaN(v);
+}
+/** A comparison's value, which must be plain by now: relative dates are resolved before compiling or evaluating. */
+export function plain(v) {
+    if (typeof v === "object" && v !== null)
+        throw new CriteriaError("a relative date reached a query unresolved; resolve it at fetch time (resolveRelative)");
+    return v;
+}

package/dist/edit/edit-model.d.ts

@@ -0,0 +1,152 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import { type ChangeSet } from "../changes/changeset.ts";
+import type { DataContext, Saved } from "../context.ts";
+import type { StoredRecord } from "../store/store.ts";
+import type { Entity, EntityType, Value } from "../schema/model.ts";
+import { type Case, type Explanation, type FieldState, type PageScope, type StateRules } from "../scope/scope.ts";
+import { type KeyText } from "../store/keys.ts";
+import { type FieldErrors } from "../validate/validate.ts";
+/**
+ * An application rule: errors by field for the current values. A rule's
+ * message wins over the metadata's for the same field, so it can say what
+ * the metadata can't ("already a member") or say it better for the screen.
+ */
+export type Rule = (values: Entity) => Readonly<Record<string, string | undefined>>;
+export interface EditOptions {
+    readonly rules?: readonly Rule[];
+}
+/**
+ * A field's page rules. With `clearWhenHidden`, hiding a shown field clears
+ * its value. `derived` gives the field a value from the page: cases for
+ * `scope.select`, or a signal computed in code, in the field's JSON form.
+ * On a read-only field it always replaces the value; on an editable one it's
+ * a suggestion that stops once the person changes the field.
+ */
+export interface FieldRules extends StateRules {
+    readonly clearWhenHidden?: boolean;
+    readonly derived?: readonly Case[] | ReadonlySignal<unknown>;
+}
+/** An edit's working state, enough to resume it after a reload. Plain data. */
+export interface EditDraft {
+    readonly key?: KeyText;
+    readonly baseline: Entity;
+    readonly values: Entity;
+    readonly etag?: string;
+    readonly forced: readonly string[];
+    /** Fields with a derived value that the person changed, so the suggestion no longer applies. */
+    readonly typed?: readonly string[];
+}
+export interface Conflict {
+    /** The record as it now is on the server. */
+    readonly theirs: Entity;
+    /** Fields both sides changed since editing began. */
+    readonly fields: readonly string[];
+}
+/**
+ * Uncommitted values for one record, apart from the stored record.
+ *
+ * Invariant: `baseline` is the stored record the edit started from (or the
+ * defaults for a new one); a field is pending when its value differs from
+ * the baseline, or when pending is forced on.
+ *
+ * A field hidden on the stored record (`StoredRecord.hidden`) is read-only,
+ * never pending and never sent: its `null` isn't a value the person has, so
+ * neither a change, a check nor a save may act on it. Every diff below goes
+ * through `#diff`, which leaves hidden fields out.
+ */
+export declare class EditModel {
+    #private;
+    readonly entitySet: string;
+    readonly type: EntityType;
+    readonly key: ReadonlySignal<KeyText | undefined>;
+    readonly baseline: ReadonlySignal<Entity>;
+    readonly values: ReadonlySignal<Entity>;
+    /** Fields the server hides from this caller on the record; their value is unknown, not empty. */
+    readonly hidden: ReadonlySignal<ReadonlySet<string>>;
+    readonly errors: ReadonlySignal<FieldErrors>;
+    /** A failure that isn't about one field. */
+    readonly formError: ReadonlySignal<string | undefined>;
+    readonly busy: ReadonlySignal<boolean>;
+    readonly conflict: ReadonlySignal<Conflict | undefined>;
+    /** The record was deleted, by someone else or elsewhere in this client. Saving is refused. */
+    readonly deleted: ReadonlySignal<boolean>;
+    readonly isNew: ReadonlySignal<boolean>;
+    readonly dirty: ReadonlySignal<boolean>;
+    /** Whether the current values would pass `validate()`, without showing errors. */
+    readonly valid: ReadonlySignal<boolean>;
+    /** Edits an existing record when `key` is given, otherwise a new one starting from `defaults`. */
+    constructor(ctx: DataContext, set: string, key?: KeyText, defaults?: Entity, options?: EditOptions);
+    /**
+     * A change shown as it was made: `before` is the baseline and `after` the
+     * values, so pending marks exactly what changed. Every field is read-only
+     * and nothing is saved.
+     */
+    static replay(ctx: DataContext, set: string, before: Entity, after: Entity, forced?: readonly string[]): EditModel;
+    /** A past change shown over its old values (`replay`), not an edit. */
+    get replaying(): boolean;
+    /** The ETag of the version the edit started from. */
+    get etag(): string | undefined;
+    /**
+     * Takes what was saved elsewhere (a deep update of a parent) as the new
+     * starting point: the saved record if given, otherwise the current values.
+     */
+    accept(saved?: StoredRecord): void;
+    /** Shows errors the server gave for these fields, such as a deep update's errors on a child. */
+    showErrors(errors: FieldErrors): void;
+    /** The working state, for keeping across a reload. */
+    draft(): EditDraft;
+    /**
+     * Takes up a draft of this record. If the stored record has moved on since,
+     * that's handled as any external change: followed where it touches nothing
+     * edited, otherwise a conflict.
+     */
+    resume(draft: EditDraft): void;
+    get(name: string): Value | undefined;
+    /**
+     * Sets a value. A field that's read-only keeps its value and shows the
+     * reason as its error. Once a field shows an error, the error follows the
+     * value: it changes with it and clears as soon as the value is valid.
+     * Empty text is null on a field marked `emptyAsNull`.
+     */
+    set(name: string, entered: Value): void;
+    /**
+     * Page rules for some fields, named `<target>.<field>` in the scope's
+     * `explain`. Call once, before the fields are shown.
+     */
+    applyRules(scope: PageScope, target: string, rules: Readonly<Record<string, FieldRules>>): void;
+    /**
+     * Whether the field holds its derived value: suggested or replaced, not
+     * typed over. False for a field without one.
+     */
+    derived(name: string): ReadonlySignal<boolean>;
+    /** The page rules behind a field's state, with what they read now. */
+    explain(name: string): Explanation[];
+    /**
+     * A field's state: its page rules, then what the metadata and the record
+     * say. Computed fields are read-only, immutable ones once saved, and every
+     * field of a deleted record; a non-nullable field is required.
+     */
+    state(name: string): ReadonlySignal<FieldState>;
+    pending(name: string): ReadonlySignal<boolean>;
+    forcePending(name: string, on: boolean): void;
+    /** Puts the starting value back; a derived field takes suggestions again from the next change. */
+    revert(name?: string): void;
+    /** Validates every field and shows the errors; returns whether the values can be saved. */
+    validate(): boolean;
+    /** The change a save would make, or `undefined` when nothing changed. */
+    changes(): ChangeSet | undefined;
+    /**
+     * Validates, then creates or updates. Field errors from the server land on
+     * their fields. On a 412 the newer record is loaded: when the other change
+     * touched none of the fields edited here, the edit is rebased onto it and
+     * sent once more; otherwise `conflict` is set. Returns `undefined` when
+     * nothing was saved, and then `errors`, `formError`, `conflict` or
+     * `deleted` says why.
+     */
+    save(): Promise<Saved | undefined>;
+    /** Takes the server's record as the new baseline and keeps local changes on top. */
+    rebase(): void;
+    /** Drops local changes in favour of the server's record. */
+    discard(): void;
+    dispose(): void;
+}