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

package/dist/edit/record-edit.js

@@ -0,0 +1,317 @@
+import { batch, computed, signal } from "@preact/signals-core";
+import { apply, creatable } from "../changes/changeset.js";
+import { ODataError } from "../odata/errors.js";
+import { keyFromText, keyText, keyValues } from "../store/keys.js";
+import { EditModel } from "./edit-model.js";
+import { ListEdit } from "./list-edit.js";
+/**
+ * Edits an existing record together with the collections it owns
+ * (`AsterData.Owned`): its fields in one edit model, each owned collection
+ * in a list edit whose new rows point at the record. Everything is one
+ * change set, one validation and one save; nothing is written per record
+ * type.
+ *
+ * Saving is one deep update (`<navigation>@delta`): the record and every
+ * owned change in one request, all or nothing.
+ */
+export class RecordEdit {
+    set;
+    key;
+    edit;
+    owned;
+    dirty;
+    valid;
+    /** Settles when every owned collection has loaded. */
+    ready;
+    #ctx;
+    #collections = [];
+    #replay;
+    constructor(ctx, set, key, options = {}, replay) {
+        this.#ctx = ctx;
+        this.set = set;
+        this.key = key;
+        this.#replay = replay !== undefined;
+        if (replay) {
+            this.edit = replay.edit;
+            this.owned = Object.freeze(replay.owned);
+            this.ready = Promise.resolve();
+        }
+        else {
+            this.edit = new EditModel(ctx, set, key, {}, options);
+            const record = this.edit.baseline.peek();
+            const owned = {};
+            for (const nav of ownedNavigations(ctx, set)) {
+                const listOptions = options.owned?.[nav.name] ?? {};
+                const collection = ctx.collection({ set: nav.target, filter: ownedFilter(nav, record), orderBy: [{ field: listOptions.positionField ?? keyField(ctx, nav.target) }] }, { pageSize: 1000 });
+                this.#collections.push(collection);
+                const defaults = Object.fromEntries(nav.keys.map(([principal, dependent]) => [dependent, record[principal] ?? null]));
+                owned[nav.name] = new ListEdit(ctx, collection, { ...listOptions, defaults: () => ({ ...listOptions.defaults?.(), ...defaults }) });
+            }
+            this.owned = Object.freeze(owned);
+            this.ready = Promise.all(this.#collections.map((c) => c.loadAll())).then(() => { });
+        }
+        const lists = Object.values(this.owned);
+        this.dirty = computed(() => this.edit.dirty.value || lists.some((l) => l.dirty.value));
+        this.valid = computed(() => this.edit.valid.value && lists.every((l) => l.valid.value));
+    }
+    /**
+     * A past change shown over what the record and its owned rows were: the
+     * record's fields and each list as replays, read-only, with pending
+     * marking exactly what the change did.
+     */
+    static replay(ctx, before, change) {
+        const set = change.set;
+        const changes = change.kind === "update" ? change.changes : {};
+        const after = change.kind === "create" ? change.values : apply(before.record, changes);
+        const edit = EditModel.replay(ctx, set, change.kind === "create" ? {} : before.record, after);
+        const owned = {};
+        for (const nav of ownedNavigations(ctx, set)) {
+            const rows = before.owned[nav.name] ?? [];
+            const ownedChanges = change.kind === "update" ? (change.owned?.[nav.name] ?? [])
+                : change.kind === "delete" ? rows.map((values) => ({ kind: "delete", set: nav.target, key: keyOfRow(ctx, nav.target, values), values }))
+                    : [];
+            owned[nav.name] = ListEdit.replay(ctx, nav.target, rows, ownedChanges);
+        }
+        const key = change.kind === "create" ? "" : keyText(change.key);
+        return new RecordEdit(ctx, set, key, {}, { edit, owned });
+    }
+    /** The record and its owned rows as they were when editing began. */
+    snapshot() {
+        const owned = {};
+        for (const [name, list] of Object.entries(this.owned)) {
+            owned[name] = list.rows.peek().filter((r) => !r.isNew).map((r) => r.edit.baseline.peek());
+        }
+        return { record: this.edit.baseline.peek(), owned };
+    }
+    /** The change a save would make, or `undefined` when nothing changed. */
+    changes() {
+        if (!this.dirty.peek())
+            return undefined;
+        const own = this.edit.changes();
+        const owned = {};
+        for (const [name, list] of Object.entries(this.owned)) {
+            const c = list.changes();
+            if (c.length)
+                owned[name] = c;
+        }
+        return {
+            kind: "update",
+            set: this.set,
+            key: keyFromText(this.key),
+            changes: own?.kind === "update" ? own.changes : {},
+            ...(Object.keys(owned).length ? { owned } : {}),
+        };
+    }
+    /** Validates every field, shown or not, and says what fails. */
+    problems() {
+        this.edit.validate();
+        const owned = {};
+        for (const [name, list] of Object.entries(this.owned)) {
+            const failing = list.rows.peek().filter((r) => !r.removing && !r.edit.validate());
+            if (failing.length)
+                owned[name] = failing.map((r) => ({ id: r.id, fields: Object.keys(r.edit.errors.peek()) }));
+        }
+        return { record: Object.keys(this.edit.errors.peek()), owned };
+    }
+    /**
+     * Validates, then writes the record and every owned change in one deep
+     * update (`<navigation>@delta`), all or nothing: new children of a new
+     * child go inside its entry. Returns `undefined` when nothing changed or
+     * something is invalid (see `problems()`). On a 412 the newer record is
+     * taken in: with no overlap the edit is sent once more, otherwise
+     * `edit.conflict` says so. Server errors land on the fields and rows they
+     * name.
+     */
+    async save() {
+        if (this.#replay || this.#busy || !this.dirty.peek())
+            return undefined;
+        if (this.edit.conflict.peek() || this.edit.deleted.peek())
+            return undefined;
+        const problems = this.problems();
+        if (problems.record.length || Object.keys(problems.owned).length)
+            return undefined;
+        this.#busy = true;
+        this.#failure.value = undefined;
+        try {
+            const before = this.snapshot();
+            const change = this.changes();
+            const { deltas, paths } = this.#deltas();
+            const own = change.kind === "update" ? Object.fromEntries(Object.entries(change.changes).map(([k, c]) => [k, c.to])) : {};
+            for (let attempt = 0;; attempt++) {
+                try {
+                    const saved = await this.#ctx.update(this.set, this.key, own, this.edit, this.edit.etag, deltas);
+                    batch(() => {
+                        this.edit.accept(saved.record);
+                        for (const list of Object.values(this.owned))
+                            list.accept();
+                    });
+                    await Promise.all(this.#collections.map((c) => c.refresh()));
+                    return { ok: true, change, before, failed: [] };
+                }
+                catch (e) {
+                    if (!(e instanceof ODataError))
+                        throw e;
+                    // A 412 takes in the newer record; with nothing overlapping, the edit goes once more.
+                    if (e.isConflict && attempt === 0 && !this.edit.conflict.peek())
+                        continue;
+                    this.#showErrors(e, paths);
+                    return { ok: false, change, before, failed: ["record"] };
+                }
+            }
+        }
+        finally {
+            this.#busy = false;
+        }
+    }
+    #busy = false;
+    /**
+     * Each owned list's changes as `@delta` entries, and the row behind each
+     * entry by its path in the request (`clauses[2]`, `clauses[0]/children[1]`),
+     * for placing errors. A new row linked to another new row goes inside that
+     * row's entry, under the navigation whose key is the link's field.
+     */
+    #deltas() {
+        const deltas = {};
+        const behind = new Map();
+        for (const [name, list] of Object.entries(this.owned)) {
+            const type = list.type;
+            const entries = [];
+            const created = new Map();
+            for (const row of list.rows.peek()) {
+                if (row.removing) {
+                    const e = { removed: keyFromText(row.id) };
+                    entries.push(e);
+                    behind.set(e, row);
+                }
+                else if (row.isNew) {
+                    const e = { values: creatable(type, row.edit.values.peek()), nested: {} };
+                    created.set(row.id, e);
+                    behind.set(e, row);
+                }
+                else if (row.edit.dirty.peek()) {
+                    const c = row.edit.changes();
+                    if (c?.kind !== "update")
+                        continue;
+                    const changed = Object.fromEntries(Object.entries(c.changes).map(([k, v]) => [k, v.to]));
+                    const e = { values: { ...keyValuesOf(type, row.edit.baseline.peek()), ...changed } };
+                    entries.push(e);
+                    behind.set(e, row);
+                }
+            }
+            for (const row of list.rows.peek()) {
+                const entry = created.get(row.id);
+                if (!entry)
+                    continue;
+                const [field, parent] = Object.entries(row.links ?? {})[0] ?? [];
+                const host = parent === undefined ? undefined : created.get(parent);
+                const nav = field === undefined ? undefined : type.navigations.find((n) => n.collection && n.keys.some(([, d]) => d === field));
+                if (host && nav && field) {
+                    const { [field]: _, ...values } = entry.values;
+                    entry.values = values;
+                    (host.nested[nav.name] ??= []).push(entry);
+                }
+                else {
+                    entries.push(entry);
+                }
+            }
+            if (entries.length)
+                deltas[name] = entries;
+        }
+        const paths = new Map();
+        const walk = (prefix, entries) => entries.forEach((e, i) => {
+            const path = `${prefix}[${i}]`;
+            const row = behind.get(e);
+            if (row)
+                paths.set(path, row);
+            if ("nested" in e)
+                for (const [nav, kids] of Object.entries(e.nested ?? {}))
+                    walk(`${path}/${nav}`, kids);
+        });
+        for (const [name, entries] of Object.entries(deltas))
+            walk(name, entries);
+        return { deltas, paths };
+    }
+    /**
+     * Puts a refused save's errors where they belong: a target naming a row's
+     * path and a field (`clauses[0]/children[1]/value`) on that row's field, a
+     * bare name on the record's; anything else is the save's `failure`.
+     */
+    #showErrors(e, paths) {
+        const byRow = new Map();
+        const own = {};
+        for (const d of e.details) {
+            const target = d.target ?? "";
+            const at = target.lastIndexOf("/");
+            const row = at < 0 ? undefined : paths.get(target.slice(0, at));
+            const field = target.slice(at + 1);
+            if (row && /^\w+$/.test(field)) {
+                const errs = byRow.get(row.edit) ?? {};
+                (errs[field] ??= []).push(d.message);
+                byRow.set(row.edit, errs);
+            }
+            else if (/^\w+$/.test(target)) {
+                (own[target] ??= []).push(d.message);
+            }
+        }
+        batch(() => {
+            if (Object.keys(own).length)
+                this.edit.showErrors(own);
+            for (const [edit, errs] of byRow)
+                edit.showErrors(errs);
+        });
+        this.#failure.value = byRow.size || Object.keys(own).length ? undefined : e.message;
+    }
+    /** Why the last save failed, when it isn't about a field. */
+    #failure = signal(undefined);
+    failure = this.#failure;
+    revert() {
+        batch(() => {
+            this.edit.revert();
+            for (const list of Object.values(this.owned))
+                list.revert();
+        });
+    }
+    draft() {
+        const owned = {};
+        for (const [name, list] of Object.entries(this.owned))
+            owned[name] = list.draft();
+        return { edit: this.edit.draft(), owned };
+    }
+    /** Takes up a draft once the owned rows are loaded. */
+    async resume(draft) {
+        await this.ready;
+        batch(() => {
+            this.edit.resume(draft.edit);
+            for (const [name, list] of Object.entries(this.owned)) {
+                const d = draft.owned[name];
+                if (d)
+                    list.resume(d);
+            }
+        });
+    }
+    dispose() {
+        this.edit.dispose();
+        for (const list of Object.values(this.owned))
+            list.dispose();
+        for (const c of this.#collections)
+            this.#ctx.release(c);
+    }
+}
+function ownedNavigations(ctx, set) {
+    return ctx.schema.set(set).type.navigations.filter((n) => n.owned && n.collection);
+}
+function ownedFilter(nav, record) {
+    const parts = nav.keys.map(([principal, dependent]) => ({ op: "eq", field: dependent, value: record[principal] ?? null }));
+    return parts.length === 1 ? parts[0] : { op: "and", args: parts };
+}
+function keyField(ctx, set) {
+    return ctx.schema.set(set).type.key[0];
+}
+/** A row's key properties by name, for a `@delta` entry. */
+function keyValuesOf(type, row) {
+    const values = keyValues(type, row);
+    return Object.fromEntries(type.key.map((k, i) => [k, values[i] ?? null]));
+}
+function keyOfRow(ctx, set, row) {
+    return ctx.schema.set(set).type.key.map((k) => row[k] ?? null);
+}

package/dist/export/csv.d.ts

@@ -0,0 +1,25 @@
+import type { DataContext } from "../context.ts";
+import type { Query } from "../criteria/ast.ts";
+import { type KeyText } from "../store/keys.ts";
+/** A plain metadata field and its CSV header, in output order. */
+export interface ExportColumn {
+    /** Direct metadata property to export. */
+    readonly field: string;
+    /** Header text; defaults to the metadata title or field name. */
+    readonly title?: string;
+}
+export interface CsvOptions {
+    /** Omit for all query results; provided keys export in this exact order. */
+    readonly keys?: readonly KeyText[];
+    readonly pageSize?: number;
+    /** Exceeding the limit rejects the entire export. Default 100,000. */
+    readonly maxRows?: number;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (rows: number) => void;
+}
+/**
+ * CSV from fresh server records, without altering the store or paging window.
+ * The query, keys and columns are captured before the first request. The server
+ * must provide snapshot consistency if records can move during a paged export.
+ */
+export declare function exportCsv(ctx: DataContext, query: Query, columns: readonly ExportColumn[], options?: CsvOptions): Promise<string>;

package/dist/export/csv.js

@@ -0,0 +1,75 @@
+import { relatedOf, resolveRelative } from "../criteria/relative.js";
+import { keyFromText } from "../store/keys.js";
+/**
+ * CSV from fresh server records, without altering the store or paging window.
+ * The query, keys and columns are captured before the first request. The server
+ * must provide snapshot consistency if records can move during a paged export.
+ */
+export async function exportCsv(ctx, query, columns, options = {}) {
+    const snapshot = structuredClone(query);
+    const q = snapshot.filter ? { ...snapshot, filter: resolveRelative(snapshot.filter, ctx.schema.set(snapshot.set).type, ctx.now(), relatedOf(ctx.schema, ctx.schema.set(snapshot.set).type)) } : snapshot;
+    const type = ctx.schema.set(q.set).type;
+    const fields = columns.map((c) => {
+        const field = type.field(c.field);
+        if (!field)
+            throw new Error(`${q.set} has no export field ${c.field}`);
+        return { field: c.field, title: c.title ?? field.title ?? c.field, type: field.type };
+    });
+    if (!fields.length)
+        throw new Error("Choose at least one export column");
+    const pageSize = options.pageSize ?? 500;
+    const maxRows = options.maxRows ?? 100_000;
+    if (!Number.isSafeInteger(pageSize) || pageSize < 1)
+        throw new Error("pageSize must be a positive safe integer");
+    if (!Number.isSafeInteger(maxRows) || maxRows < 0 || maxRows >= Number.MAX_SAFE_INTEGER)
+        throw new Error("maxRows must be a nonnegative safe integer below MAX_SAFE_INTEGER");
+    const keys = options.keys ? [...new Set(options.keys)] : undefined;
+    const check = () => options.signal?.throwIfAborted();
+    check();
+    if (keys && keys.length > maxRows)
+        throw new Error(`Export exceeds ${maxRows} rows`);
+    const lines = [fields.map((f) => csvCell(f.title, true)).join(",")];
+    let count = 0;
+    const append = (record) => {
+        if (++count > maxRows)
+            throw new Error(`Export exceeds ${maxRows} rows`);
+        lines.push(fields.map((f) => {
+            if (record.hidden?.has(f.field) || (q.select && !q.select.includes(f.field)) || (record.known && !record.known.has(f.field)))
+                return '""';
+            return csvCell(record.entity[f.field] ?? null, f.type !== "Edm.Decimal" && f.type !== "Edm.Int64");
+        }).join(","));
+    };
+    if (keys) {
+        for (const key of keys) {
+            check();
+            const record = await ctx.source.get(q.set, keyFromText(key));
+            check();
+            append(record);
+            options.onProgress?.(count);
+        }
+    }
+    else {
+        // An extra row detects overflow even when the count is absent or estimated.
+        for (let skip = 0;;) {
+            check();
+            const top = Math.min(pageSize, maxRows - count + 1);
+            const page = await ctx.source.query(q, { skip, top });
+            check();
+            for (const record of page.records)
+                append(record);
+            options.onProgress?.(count);
+            if (page.records.length < top)
+                break;
+            skip += page.records.length;
+        }
+    }
+    check();
+    return "\uFEFF" + lines.join("\r\n") + "\r\n";
+}
+/** Quote every cell; text that spreadsheets treat as a formula stays text. */
+function csvCell(value, text) {
+    let content = value === null ? "" : String(value);
+    if (text && typeof value === "string" && /^[\s\u0000-\u001f]*[=+@-]/u.test(content))
+        content = "\u0027" + content;
+    return '"' + content.replaceAll('"', '""') + '"';
+}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+export { ProgressState, progressPolicy, DEFAULT_PROGRESS_POLICY, type ProgressPhase, type ProgressPolicy, type ProgressWork } from "./progress/status.ts";
+export type * from "./schema/model.ts";
+export { Lifetime } from "./composition/lifetime.ts";
+export { Command, command, type CommandOptions } from "./composition/command.ts";
+export { parseCsdl, SchemaError } from "./schema/csdl.ts";
+export type { Criteria, Query, RelativeDate, SortKey } from "./criteria/ast.ts";
+export { FilterDraft, filterOperators, describeCriteria, type FilterNode, type FilterGroup, type FilterCondition, type FilterRelated, type FilterProblem, type FilterResult, type FilterChange } from "./criteria/filter-draft.ts";
+export { hasRelative, isRelative, resolveRelative } from "./criteria/relative.ts";
+export { criteriaRule, type CriteriaValidator, type OwnCriteria, type OwnTest } from "./validate/criteria-rule.ts";
+export { parseTemplate, TemplateError, type Template } from "./template/template.ts";
+export { toApply, toFilter, toOrderBy, toQueryString, formatLiteral, CriteriaError, type Aggregate } from "./criteria/compile.ts";
+export { matches, compareValues, sortComparator, type Related } from "./criteria/evaluate.ts";
+export type { Method, ODataRequest, ODataResponse, Transport } from "./transport.ts";
+export { fetchTransport } from "./transport.ts";
+export { Authentication, AuthenticationError, type AuthenticationOptions, type AuthenticationChallenge, type AuthenticationRecovery, type AuthenticationFailure } from "./authentication.ts";
+export { ODataError, type ErrorDetail } from "./odata/errors.ts";
+export { ODataSource, type Page } from "./odata/source.ts";
+export { keyOf, keyText, keyValues, keyFromText, type KeyText, type KeyValues } from "./store/keys.ts";
+export { RecordStore, type StoredRecord, type StoreChange, type Origin } from "./store/store.ts";
+export { Collection, type CollectionOptions, type CollectionStatus } from "./collection/collection.ts";
+export { aggregate, countBy, countWhere, subtractExact, sum, sumValues } from "./collection/aggregate.ts";
+export { apply, creatable, diff, invert, merge, writable, type ChangeSet, type FieldChange, type OwnedChanges } from "./changes/changeset.ts";
+export { validateEntity, validateField, type FieldErrors } from "./validate/validate.ts";
+export { EditModel, type Conflict, type EditDraft, type EditOptions, type FieldRules, type Rule } from "./edit/edit-model.ts";
+export { DataContext, type Saved } from "./context.ts";
+export { Selection, selectionOptionsError, type SelectionOptions } from "./selection/selection.ts";
+export { PageScope, toCriteria, DEFAULT_STATE, MAX_HOPS, type Case, type Condition, type Effect, type Explanation, type FieldState, type Publication, type Ruled, type ScopeName, type ScopeSchema, type SelectedValue, type StateRules, } from "./scope/scope.ts";
+export { collectionPublication, editPublication, inputPublication, listPublication, selectionPublication, valuesPublication } from "./scope/publications.ts";
+export { SharedFilters, compatible, filtersPublication, selectionShare, type Applied, type Consumed, type ConsumeOptions, type Contribution, type ContributionKind, type FilterSnapshot, type Shared, type SkippedContribution, } from "./scope/filters.ts";
+export { ListEdit, type ListDraft, type ListEditOptions, type ListRow, type ListSaveResult } from "./edit/list-edit.ts";
+export { RecordEdit, type RecordDraft, type RecordEditOptions, type RecordProblems, type RecordSave, type RecordSnapshot } from "./edit/record-edit.ts";
+export { Groups, type GroupRow } from "./collection/groups.ts";
+export { Grouping, type GroupingRow, type GroupingHeader, type GroupingRecord, type GroupingOptions } from "./collection/grouping.ts";
+export { Tree, type TreeOptions, type TreeRow, type FilterMode } from "./tree/tree.ts";
+export { Summary } from "./collection/summary.ts";
+export { exportCsv, type CsvOptions, type ExportColumn } from "./export/csv.ts";
+export { SessionActivity, ActivityTask, type ActivityOptions, type ActivityRun, type InactivePolicy } from "./composition/activity.ts";
+export { KeyedSessions, KeyedSession, type SessionDescriptor, type SessionResource, type SessionMount, type KeyedSessionsOptions, type SessionStatus } from "./composition/sessions.ts";

package/dist/index.js

@@ -0,0 +1,35 @@
+export { ProgressState, progressPolicy, DEFAULT_PROGRESS_POLICY } from "./progress/status.js";
+export { Lifetime } from "./composition/lifetime.js";
+export { Command, command } from "./composition/command.js";
+export { parseCsdl, SchemaError } from "./schema/csdl.js";
+export { FilterDraft, filterOperators, describeCriteria } from "./criteria/filter-draft.js";
+export { hasRelative, isRelative, resolveRelative } from "./criteria/relative.js";
+export { criteriaRule } from "./validate/criteria-rule.js";
+export { parseTemplate, TemplateError } from "./template/template.js";
+export { toApply, toFilter, toOrderBy, toQueryString, formatLiteral, CriteriaError } from "./criteria/compile.js";
+export { matches, compareValues, sortComparator } from "./criteria/evaluate.js";
+export { fetchTransport } from "./transport.js";
+export { Authentication, AuthenticationError } from "./authentication.js";
+export { ODataError } from "./odata/errors.js";
+export { ODataSource } from "./odata/source.js";
+export { keyOf, keyText, keyValues, keyFromText } from "./store/keys.js";
+export { RecordStore } from "./store/store.js";
+export { Collection } from "./collection/collection.js";
+export { aggregate, countBy, countWhere, subtractExact, sum, sumValues } from "./collection/aggregate.js";
+export { apply, creatable, diff, invert, merge, writable } from "./changes/changeset.js";
+export { validateEntity, validateField } from "./validate/validate.js";
+export { EditModel } from "./edit/edit-model.js";
+export { DataContext } from "./context.js";
+export { Selection, selectionOptionsError } from "./selection/selection.js";
+export { PageScope, toCriteria, DEFAULT_STATE, MAX_HOPS, } from "./scope/scope.js";
+export { collectionPublication, editPublication, inputPublication, listPublication, selectionPublication, valuesPublication } from "./scope/publications.js";
+export { SharedFilters, compatible, filtersPublication, selectionShare, } from "./scope/filters.js";
+export { ListEdit } from "./edit/list-edit.js";
+export { RecordEdit } from "./edit/record-edit.js";
+export { Groups } from "./collection/groups.js";
+export { Grouping } from "./collection/grouping.js";
+export { Tree } from "./tree/tree.js";
+export { Summary } from "./collection/summary.js";
+export { exportCsv } from "./export/csv.js";
+export { SessionActivity, ActivityTask } from "./composition/activity.js";
+export { KeyedSessions, KeyedSession } from "./composition/sessions.js";

package/dist/odata/errors.d.ts

@@ -0,0 +1,25 @@
+/** One problem in a failed request. `message` is the server's and is what's shown; `code` and `params` are stable, for localising it. */
+export interface ErrorDetail {
+    readonly code: string;
+    readonly message: string;
+    /** A property path, when the detail is about one field. */
+    readonly target?: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+}
+/** A failed OData request, with the service's error object when it sent one. */
+export declare class ODataError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly target: string | undefined;
+    readonly details: readonly ErrorDetail[];
+    /** The current ETag the server sent with a 412. */
+    readonly etag: string | undefined;
+    constructor(status: number, code: string, message: string, details?: readonly ErrorDetail[], target?: string, etag?: string);
+    /** Someone changed the record since it was read (412). */
+    get isConflict(): boolean;
+    /** The key is already taken (409). */
+    get isDuplicate(): boolean;
+    /** Detail messages by property path. Details without a target are left out. */
+    fieldErrors(): Record<string, string[]>;
+}
+export declare function errorFromResponse(status: number, body: string, etag?: string): ODataError;

package/dist/odata/errors.js

@@ -0,0 +1,56 @@
+/** A failed OData request, with the service's error object when it sent one. */
+export class ODataError extends Error {
+    status;
+    code;
+    target;
+    details;
+    /** The current ETag the server sent with a 412. */
+    etag;
+    constructor(status, code, message, details = [], target, etag) {
+        super(message);
+        this.name = "ODataError";
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.target = target;
+        this.etag = etag;
+    }
+    /** Someone changed the record since it was read (412). */
+    get isConflict() {
+        return this.status === 412;
+    }
+    /** The key is already taken (409). */
+    get isDuplicate() {
+        return this.status === 409;
+    }
+    /** Detail messages by property path. Details without a target are left out. */
+    fieldErrors() {
+        const out = {};
+        for (const d of this.details) {
+            if (d.target)
+                (out[d.target] ??= []).push(d.message);
+        }
+        return out;
+    }
+}
+export function errorFromResponse(status, body, etag) {
+    try {
+        const parsed = JSON.parse(body);
+        const e = parsed.error;
+        if (e && typeof e === "object") {
+            const details = Array.isArray(e.details)
+                ? e.details.map((d) => ({
+                    code: String(d.code ?? ""),
+                    message: String(d.message ?? ""),
+                    ...(typeof d.target === "string" ? { target: d.target } : {}),
+                    ...(typeof d.params === "object" && d.params !== null && !Array.isArray(d.params) ? { params: d.params } : {}),
+                }))
+                : [];
+            return new ODataError(status, String(e.code ?? status), String(e.message ?? `Request failed with status ${status}`), details, typeof e.target === "string" ? e.target : undefined, etag);
+        }
+    }
+    catch {
+        // Not JSON: fall through to a generic error.
+    }
+    return new ODataError(status, String(status), `Request failed with status ${status}`, [], undefined, etag);
+}

package/dist/odata/source.d.ts

@@ -0,0 +1,65 @@
+import type { Query } from "../criteria/ast.ts";
+import { type Aggregate } from "../criteria/compile.ts";
+import type { Criteria, SortKey } from "../criteria/ast.ts";
+import type { Entity, Schema, Value } from "../schema/model.ts";
+import type { KeyValues } from "../store/keys.ts";
+import type { StoredRecord } from "../store/store.ts";
+import type { Transport } from "../transport.ts";
+export interface Page {
+    readonly records: readonly StoredRecord[];
+    /** Present when the request asked for `$count` and the server gave one. */
+    readonly count?: number;
+    /** `count` is the server's estimate (`@AsterData.CountEstimated`), not exact. */
+    readonly estimated?: boolean;
+}
+/** OData 4.01 over a transport. Every failure is an `ODataError`. */
+export declare class ODataSource {
+    #private;
+    readonly schema: Schema;
+    constructor(schema: Schema, transport: Transport);
+    static connect(transport: Transport): Promise<ODataSource>;
+    /**
+     * 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.
+     */
+    query(query: Query, range?: {
+        skip?: number;
+        top?: number;
+        count?: boolean;
+        exact?: boolean;
+    }): Promise<Page>;
+    /**
+     * 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.
+     */
+    aggregate(set: string, request: {
+        readonly filter?: Criteria;
+        readonly groupBy?: readonly string[];
+        readonly aggregates?: readonly Aggregate[];
+        readonly orderBy?: readonly SortKey[];
+    }): Promise<Record<string, Value>[]>;
+    get(set: string, key: KeyValues): Promise<StoredRecord>;
+    create(set: string, values: Entity): Promise<StoredRecord>;
+    /**
+     * 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.
+     */
+    update(set: string, key: KeyValues, changes: Entity, etag: string | undefined, deltas?: Deltas): Promise<StoredRecord>;
+    delete(set: string, key: KeyValues, etag: string | undefined): Promise<void>;
+}
+/**
+ * One change to an owned child in a deep update: its key and changed values,
+ * a new child's values (with its own new children by navigation), or a
+ * removal by key.
+ */
+export type DeltaEntry = {
+    readonly values: Entity;
+    readonly nested?: Readonly<Record<string, readonly DeltaEntry[]>>;
+} | {
+    readonly removed: KeyValues;
+};
+/** Deep update changes by owned navigation. */
+export type Deltas = Readonly<Record<string, readonly DeltaEntry[]>>;