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

package/dist/odata/source.js

@@ -0,0 +1,193 @@
+import { formatLiteral, toApply, toQueryString } from "../criteria/compile.js";
+import { parseCsdl } from "../schema/csdl.js";
+import { errorFromResponse } from "./errors.js";
+/** Instance annotations aster-odata writes (`Aster.Data.V1`, alias `AsterData`). */
+const COUNT_ESTIMATED = ["@AsterData.CountEstimated", "@Aster.Data.V1.CountEstimated"];
+const HIDDEN = ["@AsterData.Hidden", "@Aster.Data.V1.Hidden"];
+const ACCEPT = "application/json;odata.metadata=minimal;IEEE754Compatible=true";
+/** OData 4.01 over a transport. Every failure is an `ODataError`. */
+export class ODataSource {
+    schema;
+    #transport;
+    constructor(schema, transport) {
+        this.schema = schema;
+        this.#transport = transport;
+    }
+    static async connect(transport) {
+        const res = await transport({ method: "GET", url: "$metadata", headers: { accept: "application/json" } });
+        if (res.status !== 200)
+            throw errorFromResponse(res.status, res.body);
+        return new ODataSource(parseCsdl(JSON.parse(res.body)), transport);
+    }
+    /**
+     * One range of a query's results. With `count`, the total too; `exact`
+     * asks for an exact one (`Prefer: aster.count=exact`) where the server
+     * would otherwise estimate it or leave it out.
+     */
+    async query(query, range = {}) {
+        const options = [toQueryString(query, this.schema)];
+        if (range.skip)
+            options.push(`$skip=${range.skip}`);
+        if (range.top !== undefined)
+            options.push(`$top=${range.top}`);
+        if (range.count)
+            options.push("$count=true");
+        const qs = options.filter(Boolean).join("&");
+        const headers = range.count && range.exact ? { prefer: "aster.count=exact" } : undefined;
+        let body = await this.#json("GET", qs ? `${query.set}?${qs}` : query.set, undefined, headers);
+        const count = body["@odata.count"];
+        const estimated = COUNT_ESTIMATED.some((a) => body[a] === true);
+        const records = [];
+        for (;;) {
+            const value = Array.isArray(body.value) ? body.value : [];
+            records.push(...value.map(toRecord));
+            const next = body["@odata.nextLink"];
+            if (typeof next !== "string" || (range.top !== undefined && records.length >= range.top))
+                break;
+            body = await this.#json("GET", relativeToRoot(next, query.set));
+        }
+        return {
+            records: range.top === undefined ? records : records.slice(0, range.top),
+            ...(count === undefined ? {} : { count: Number(count), ...(estimated ? { estimated } : {}) }),
+        };
+    }
+    /**
+     * Counts and aggregates over a set, grouped by `groupBy` (one row per
+     * distinct combination) or over all of it. Rows hold the group values,
+     * `count`, and each aggregate's alias.
+     */
+    async aggregate(set, request) {
+        const entitySet = this.schema.set(set);
+        const apply = toApply(entitySet.type, request.filter, request.groupBy ?? [], request.aggregates ?? [], entitySet, this.schema);
+        const order = request.orderBy?.length ? `&$orderby=${encodeURIComponent(request.orderBy.map((k) => `${k.field}${k.descending ? " desc" : ""}`).join(","))}` : "";
+        let body = await this.#json("GET", `${set}?$apply=${encodeURIComponent(apply)}${order}`);
+        const values = [];
+        for (;;) {
+            if (Array.isArray(body.value))
+                values.push(...body.value);
+            const next = body["@odata.nextLink"];
+            if (typeof next !== "string")
+                break;
+            body = await this.#json("GET", relativeToRoot(next, set));
+        }
+        return values.map((row) => {
+            const out = {};
+            for (const [k, v] of Object.entries(row))
+                if (!k.includes("@"))
+                    out[k] = v;
+            return out;
+        });
+    }
+    async get(set, key) {
+        return toRecord(await this.#json("GET", this.#entityUrl(set, key)));
+    }
+    async create(set, values) {
+        return toRecord(await this.#json("POST", set, JSON.stringify(values), { prefer: "return=representation" }));
+    }
+    /**
+     * PATCH with `If-Match`; returns the updated record. `deltas` carries
+     * owned collections' changes as `<navigation>@delta`, so the record and
+     * its children change in one request, all or nothing.
+     */
+    async update(set, key, changes, etag, deltas = {}) {
+        const type = this.schema.set(set).type;
+        const body = { ...changes };
+        for (const [nav, entries] of Object.entries(deltas)) {
+            const target = type.navigation(nav)?.target;
+            if (!target)
+                throw new Error(`${type.name} has no navigation ${nav}`);
+            body[`${nav}@delta`] = entries.map((e) => this.#deltaEntry(target, e));
+        }
+        return toRecord(await this.#json("PATCH", this.#entityUrl(set, key), JSON.stringify(body), {
+            prefer: "return=representation",
+            ...ifMatch(etag),
+        }));
+    }
+    /** An entry of `@delta`: a removal by `@id`, or values with any children inserted under it. */
+    #deltaEntry(set, entry) {
+        if ("removed" in entry)
+            return { "@removed": { reason: "deleted" }, "@id": this.#entityUrl(set, entry.removed) };
+        const type = this.schema.set(set).type;
+        const out = { ...entry.values };
+        for (const [nav, children] of Object.entries(entry.nested ?? {})) {
+            const target = type.navigation(nav)?.target;
+            if (!target)
+                throw new Error(`${type.name} has no navigation ${nav}`);
+            out[nav] = children.map((c) => this.#deltaEntry(target, c));
+        }
+        return out;
+    }
+    async delete(set, key, etag) {
+        await this.#send("DELETE", this.#entityUrl(set, key), undefined, ifMatch(etag));
+    }
+    #entityUrl(set, key) {
+        const type = this.schema.set(set).type;
+        const literal = (name, v) => {
+            const field = type.field(name);
+            if (!field)
+                throw new Error(`${type.name} has no key property ${name}`);
+            return encodeURIComponent(formatLiteral(v, field));
+        };
+        const parts = type.key.map((name, i) => {
+            const v = key[i];
+            if (v === undefined)
+                throw new Error(`missing key value for ${name}`);
+            return type.key.length === 1 ? literal(name, v) : `${name}=${literal(name, v)}`;
+        });
+        return `${set}(${parts.join(",")})`;
+    }
+    async #json(method, url, body, headers) {
+        const res = await this.#send(method, url, body, headers);
+        const parsed = JSON.parse(res.body);
+        if (res.headers.etag && parsed["@odata.etag"] === undefined)
+            parsed["@odata.etag"] = res.headers.etag;
+        return parsed;
+    }
+    async #send(method, url, body, headers) {
+        const request = {
+            method,
+            url,
+            headers: {
+                accept: ACCEPT,
+                ...(body === undefined ? {} : { "content-type": "application/json;IEEE754Compatible=true" }),
+                ...headers,
+            },
+            ...(body === undefined ? {} : { body }),
+        };
+        const res = await this.#transport(request);
+        if (res.status >= 400)
+            throw errorFromResponse(res.status, res.body, res.headers.etag);
+        return res;
+    }
+}
+/**
+ * `If-Match` whenever an ETag is held, whatever `$metadata` declares. With
+ * none on an ETag-bearing set, the server answers 428 rather than overwriting.
+ */
+function ifMatch(etag) {
+    return etag !== undefined ? { "if-match": etag } : {};
+}
+/** Next links are absolute; the transport takes URLs relative to the service root. */
+function relativeToRoot(link, set) {
+    const at = link.lastIndexOf(`/${set}`);
+    return at < 0 ? link : link.slice(at + 1);
+}
+/**
+ * Splits control information (`@odata.*`) from the entity's properties.
+ * `@AsterData.Hidden` lists the fields the caller may not see on this
+ * record; they arrive as `null`.
+ */
+function toRecord(json) {
+    const entity = {};
+    let etag;
+    let hidden;
+    for (const [name, v] of Object.entries(json)) {
+        if (name === "@odata.etag")
+            etag = String(v);
+        else if (HIDDEN.includes(name) && Array.isArray(v) && v.length > 0)
+            hidden = new Set(v.map(String));
+        else if (!name.includes("@"))
+            entity[name] = v;
+    }
+    return { entity, ...(etag === undefined ? {} : { etag }), ...(hidden ? { hidden } : {}) };
+}

package/dist/progress/status.d.ts

@@ -0,0 +1,29 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+export interface ProgressPolicy {
+    /** Milliseconds before a busy operation becomes visually visible. */
+    readonly delayMs?: number;
+    /** Minimum total visible time, including any completion message. */
+    readonly minVisibleMs?: number;
+}
+export declare const DEFAULT_PROGRESS_POLICY: Readonly<{
+    delayMs: 250;
+    minVisibleMs: 400;
+}>;
+export type ProgressPhase = "idle" | "waiting" | "working" | "complete" | "error";
+export interface ProgressWork {
+    readonly busy: boolean;
+    readonly error?: unknown;
+}
+/** Validate and snapshot presentation timing without changing the source operation. */
+export declare function progressPolicy(options?: ProgressPolicy): Readonly<Required<ProgressPolicy>>;
+/** Delayed presentation of borrowed work; actual busy/error values remain immediate. */
+export declare class ProgressState {
+    #private;
+    readonly busy: ReadonlySignal<boolean>;
+    readonly error: ReadonlySignal<unknown>;
+    readonly phase: ReadonlySignal<ProgressPhase>;
+    readonly visible: ReadonlySignal<boolean>;
+    constructor(source: () => ProgressWork, policy?: ProgressPolicy | (() => ProgressPolicy));
+    /** Stops timers/subscriptions; never cancels or completes the borrowed operation. */
+    dispose(): void;
+}

package/dist/progress/status.js

@@ -0,0 +1,105 @@
+import { batch, computed, effect, signal, untracked } from "@preact/signals-core";
+export const DEFAULT_PROGRESS_POLICY = Object.freeze({ delayMs: 250, minVisibleMs: 400 });
+/** Validate and snapshot presentation timing without changing the source operation. */
+export function progressPolicy(options = {}) {
+    if (!options || typeof options !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(options)))
+        throw new TypeError("Progress policy must be a plain object");
+    for (const [key, value] of Object.entries(options)) {
+        if (!["delayMs", "minVisibleMs"].includes(key))
+            throw new TypeError(`Unknown progress policy '${key}'`);
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 2_147_483_647)
+            throw new RangeError(`${key} must be an integer between 0 and 2147483647`);
+    }
+    return Object.freeze({ ...DEFAULT_PROGRESS_POLICY, ...options });
+}
+/** Delayed presentation of borrowed work; actual busy/error values remain immediate. */
+export class ProgressState {
+    #busy = signal(false);
+    #error = signal(undefined);
+    #phase = signal("idle");
+    busy = this.#busy;
+    error = this.#error;
+    phase = this.#phase;
+    visible = computed(() => ["working", "complete", "error"].includes(this.phase.value));
+    #stop;
+    #timer;
+    #revision = 0;
+    #disposed = false;
+    #started;
+    #shown;
+    #work = { busy: false };
+    #policy = DEFAULT_PROGRESS_POLICY;
+    constructor(source, policy = {}) {
+        const fixed = typeof policy === "function" ? DEFAULT_PROGRESS_POLICY : progressPolicy(policy);
+        const readPolicy = typeof policy === "function" ? policy : () => fixed;
+        this.#stop = effect(() => {
+            const work = source();
+            if (!work || typeof work.busy !== "boolean")
+                throw new TypeError("Progress work must expose a boolean busy value");
+            const settings = progressPolicy(readPolicy());
+            untracked(() => this.#update(work, settings));
+        });
+    }
+    #update(work, policy) {
+        if (this.#disposed)
+            return;
+        this.#cancel();
+        const now = performance.now();
+        if (work.busy && !this.#busy.peek())
+            this.#started = now;
+        this.#work = { busy: work.busy, error: work.error };
+        this.#policy = policy;
+        batch(() => {
+            this.#busy.value = work.busy;
+            this.#error.value = work.error;
+            if (work.error !== undefined && work.error !== null) {
+                this.#shown = undefined;
+                this.#phase.value = "error";
+                return;
+            }
+            if (work.busy) {
+                if (this.#shown !== undefined) {
+                    this.#phase.value = "working";
+                    return;
+                }
+                const remaining = policy.delayMs - (now - (this.#started ?? now));
+                if (remaining > 0) {
+                    this.#phase.value = "waiting";
+                    this.#schedule(remaining);
+                }
+                else {
+                    this.#shown = now;
+                    this.#phase.value = "working";
+                }
+                return;
+            }
+            this.#started = undefined;
+            const remaining = this.#shown === undefined ? 0 : policy.minVisibleMs - (now - this.#shown);
+            if (remaining > 0) {
+                this.#phase.value = "complete";
+                this.#schedule(remaining);
+            }
+            else {
+                this.#shown = undefined;
+                this.#phase.value = "idle";
+            }
+        });
+    }
+    #schedule(ms) {
+        const revision = this.#revision;
+        this.#timer = setTimeout(() => {
+            if (!this.#disposed && revision === this.#revision)
+                this.#update(this.#work, this.#policy);
+        }, ms);
+    }
+    #cancel() { this.#revision++; clearTimeout(this.#timer); this.#timer = undefined; }
+    /** Stops timers/subscriptions; never cancels or completes the borrowed operation. */
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#cancel();
+        this.#stop();
+        this.#phase.value = "idle";
+    }
+}

package/dist/schema/csdl.d.ts

@@ -0,0 +1,13 @@
+import type { Schema } from "./model.ts";
+/** A metadata problem, with the JSON path of the offending member. */
+export declare class SchemaError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Parses a CSDL JSON 4.01 `$metadata` document. Throws `SchemaError` when
+ * the document is malformed; a property it can't model (a stream, an
+ * untyped or complex value, a collection) is left out and listed in
+ * `skipped`, and the rest of the schema stands.
+ */
+export declare function parseCsdl(json: unknown): Schema;