@texuli/core 0.6.0 → 0.8.0

package/README.md

@@ -12,9 +12,9 @@ when you need Texuli's URL policy to sanitize links and media from agents
 or users. It has no runtime dependencies and imports no UI framework.
 
 > **Status: 0.x release.** Texuli is in development. The packages are
-> published to npm as `0.6.0`, a pre-1.0 release (1.0.0 will be the first
-> stable release). Under 0.x, a new minor (`0.7.0`) may contain breaking
-> changes, so pin the exact version or use `^0.6.0`, which accepts only 0.6.x.
+> published to npm as `0.8.0`, a pre-1.0 release (1.0.0 will be the first
+> stable release). Under 0.x, a new minor (`0.9.0`) may contain breaking
+> changes, so pin the exact version or use `^0.8.0`, which accepts only 0.8.x.
 
 ## Install
 
@@ -59,8 +59,8 @@ window.addEventListener('keydown', (event) => {
 
 Everything in the table below is available from the root entry
 (`@texuli/core`) and from its own subpath (`@texuli/core/<subpath>`), except
-the editor, lazy-chunk, motion, markup and ZIP texels, which are
-subpath-only. Import subpaths to keep bundles narrow.
+the editor, lazy-chunk, motion, markup, ZIP, expression, data-source and
+i18n texels, which are subpath-only. Import subpaths to keep bundles narrow.
 
 ## What's inside
 
@@ -90,6 +90,9 @@ subpath-only. Import subpaths to keep bundles narrow.
 | Rich text editor model | `editor-model`, `editor-transforms`, `editor-history`, `editor-keymap`, `editor-markdown` | Document model, transforms, undo history, keymap, Markdown import and export (subpath only) |
 | Markup builders | `markup` | `el`, `text`, `linkUrl`, `imageUrl`, `serializeXml`, `serializeHtml`: escaped XML and HTML with no raw-markup API (subpath only) |
 | ZIP writer | `zip` | `writeZip`, `writeZipAsync`, `crc32`, `compressBytes`: deterministic archives, deflated where the platform can (subpath only) |
+| Expressions | `expression` | `parseExpression`, `parseExpressionText`, `analyzeExpression`, `evaluateExpression`, `CORE_FUNCTIONS`: the closed, bounded expression language of ADR-015 (subpath only; new in 0.8.0) |
+| Data sources | `data-source` | `defineSource`, `createSourceRegistry`, `checkSourceQuery`, `createSourceLoader`, `createSourceCollection`, `sourceError`: host-registered sources, the closed query, deduplicated, cancellable, retried and cached reads, optimistic writes with rollback, typed errors (ADR-015; subpath only; new in 0.8.0) |
+| Message catalogs | `i18n` | `createI18n`, `parseCatalog`, `formatMessage`, `resolveLabel`, `I18N_CONTEXT`, `pseudoLocalize`: component labels through one catalog, with lazy locales (ADR-016; subpath only; new in 0.8.0) |
 
 The table names the headline exports; each subpath's TypeScript
 declarations list the full surface.
@@ -158,6 +161,9 @@ Ships in `0.6.0`; the `0.5.0` release predates it:
 - Rich text editor model: [core-editor.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-editor.md)
 - Static outputs: [core-markup.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-markup.md) (escaped XML and HTML builders) and [core-zip.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-zip.md) (the ZIP writer)
 - Motion (`@texuli/core/motion`: animate, presence, FLIP, shared elements, timelines, springs): [core-motion.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-motion.md)
+- Expressions (`@texuli/core/expression`: the closed AST, its text form, analysis and the bounded evaluator; new in 0.8.0): [core-expression.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-expression.md)
+- Data sources (`@texuli/core/data-source`: declarations, the closed query, the loader, collections and errors; new in 0.8.0): [core-data-source.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-data-source.md)
+- Message catalogs (`@texuli/core/i18n`: catalogs, lazy locales, plural and select messages, the instance prop → context → English resolution and the pseudo-locale; new in 0.8.0): [core-i18n.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-i18n.md)
 - Every texel's contract: [packages/core/docs](https://github.com/DailybotHQ/texuli/tree/main/packages/core/docs)
 - Security model: [SECURITY.md](https://github.com/DailybotHQ/texuli/blob/main/docs/SECURITY.md)
 

package/dist/data-source/collection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A source collection: the rows one view shows for one query, paged, with
+ * optimistic writes. Confirmed rows (`base`) and pending writes are kept
+ * apart; what a view sees is the base with every pending write applied in
+ * order. A write that succeeds folds the source's row into the base; one
+ * that fails is dropped, which rolls it back exactly, even while other
+ * writes are pending. Framework-free: a view subscribes and re-reads
+ * `state`.
+ */
+import { type SourceError } from './errors.js';
+import type { SourceLoader, SourceResult } from './loader.js';
+import type { SourceQuery, SourceValue } from './query.js';
+import type { SourceRow, SourceRowId } from './registry.js';
+import type { SourceDescriptor } from './schema.js';
+export type SourceCollectionStatus = 'idle' | 'loading' | 'ready' | 'error';
+export interface SourceCollectionState {
+    readonly status: SourceCollectionStatus;
+    /** Confirmed rows with the pending writes applied. */
+    readonly rows: readonly SourceRow[];
+    /** Why the last load failed (`status` is `error`). Rows from before it stay. */
+    readonly error: SourceError | null;
+    /** A reload is running over rows already shown. */
+    readonly refreshing: boolean;
+    readonly hasMore: boolean;
+    readonly loadingMore: boolean;
+    /** Why the last `loadMore` failed; the loaded rows stay. */
+    readonly moreError: SourceError | null;
+    readonly total: number | null;
+    /** Optimistic writes in flight. */
+    readonly pending: number;
+    /** The last write that failed (and was rolled back). Cleared by the next write. */
+    readonly writeError: SourceError | null;
+    /** Bumped on every change. */
+    readonly version: number;
+}
+export interface SourceCollectionOptions {
+    /** Reload when another view writes to the same source. Default `true`. */
+    autoRefresh?: boolean;
+    /** Where optimistic creates appear. Default `end`. */
+    createAt?: 'start' | 'end';
+}
+export interface SourceCollection {
+    readonly state: SourceCollectionState;
+    /** The source's descriptor, or `null` when the name or query was refused. */
+    readonly descriptor: SourceDescriptor | null;
+    /** The validated query, or `null` when it was refused. */
+    readonly query: SourceQuery | null;
+    /** Load the first page (again). Rows already shown stay until it lands. */
+    load(): Promise<void>;
+    /** Append the next page, when there is one. */
+    loadMore(): Promise<void>;
+    /** After a failure: reload, or ask for the failed next page again. */
+    retry(): Promise<void>;
+    /** Change fields of a row, optimistically. */
+    update(id: SourceRowId, changes: Readonly<Record<string, SourceValue>>): Promise<SourceResult<SourceRow>>;
+    /** Add a row, optimistically (with a temporary key until the source answers). */
+    create(values: Readonly<Record<string, SourceValue>>): Promise<SourceResult<SourceRow>>;
+    /** Remove a row, optimistically. */
+    remove(id: SourceRowId): Promise<SourceResult<null>>;
+    subscribe(listener: (state: SourceCollectionState) => void): () => void;
+    /** Cancel everything in flight and stop listening. The state stays readable. */
+    destroy(): void;
+}
+/** The prefix of a temporary key: an optimistic row the source has not confirmed. */
+export declare const PENDING_ROW_PREFIX = "pending:";
+/** Create a collection over one source and query. Nothing loads until `load()`. */
+export declare function createSourceCollection(loader: SourceLoader, name: string, query: unknown, options?: SourceCollectionOptions): SourceCollection;

package/dist/data-source/collection.js

@@ -0,0 +1,247 @@
+/**
+ * A source collection: the rows one view shows for one query, paged, with
+ * optimistic writes. Confirmed rows (`base`) and pending writes are kept
+ * apart; what a view sees is the base with every pending write applied in
+ * order. A write that succeeds folds the source's row into the base; one
+ * that fails is dropped, which rolls it back exactly, even while other
+ * writes are pending. Framework-free: a view subscribes and re-reads
+ * `state`.
+ */
+import { sourceError } from "./errors.js";
+/** The prefix of a temporary key: an optimistic row the source has not confirmed. */
+export const PENDING_ROW_PREFIX = 'pending:';
+const INITIAL = Object.freeze({
+    status: 'idle',
+    rows: Object.freeze([]),
+    error: null,
+    refreshing: false,
+    hasMore: false,
+    loadingMore: false,
+    moreError: null,
+    total: null,
+    pending: 0,
+    writeError: null,
+    version: 0,
+});
+function project(row, like, fields, key) {
+    const names = like ? Object.keys(like) : fields ? [key, ...fields] : Object.keys(row);
+    const out = {};
+    for (const name of names) {
+        if (Object.hasOwn(row, name))
+            Object.defineProperty(out, name, { value: row[name] ?? null, enumerable: true });
+    }
+    return Object.freeze(out);
+}
+/** Create a collection over one source and query. Nothing loads until `load()`. */
+export function createSourceCollection(loader, name, query, options = {}) {
+    const resolution = loader.checkQuery(name, query);
+    const descriptor = resolution.ok ? resolution.descriptor : null;
+    const checked = resolution.ok ? resolution.query : null;
+    const key = descriptor?.key ?? 'id';
+    const origin = Object.freeze({ collection: name });
+    const listeners = new Set();
+    let state = resolution.ok
+        ? INITIAL
+        : Object.freeze({ ...INITIAL, status: 'error', error: resolution.error, version: 1 });
+    let base = [];
+    let pending = [];
+    let nextCursor = null;
+    let nextOffset = null;
+    let loadController = null;
+    let moreController = null;
+    const writeControllers = new Set();
+    let seq = 0;
+    let destroyed = false;
+    const same = (row, id) => row[key] === id;
+    function visible() {
+        let rows = base;
+        for (const write of pending) {
+            if (write.kind === 'update') {
+                rows = rows.map((row) => same(row, write.id)
+                    ? Object.freeze({ ...row, ...write.changes, [key]: row[key] ?? null })
+                    : row);
+            }
+            else if (write.kind === 'remove') {
+                rows = rows.filter((row) => !same(row, write.id));
+            }
+            else {
+                rows = options.createAt === 'start' ? [write.row, ...rows] : [...rows, write.row];
+            }
+        }
+        return Object.freeze(rows);
+    }
+    function commit(patch) {
+        state = Object.freeze({
+            ...state,
+            ...patch,
+            rows: visible(),
+            pending: pending.length,
+            version: state.version + 1,
+        });
+        for (const listener of [...listeners]) {
+            try {
+                listener(state);
+            }
+            catch {
+                // A listener's failure never stops the others.
+            }
+        }
+    }
+    function applyPage(page) {
+        nextCursor = page.nextCursor;
+        nextOffset = page.nextOffset;
+    }
+    async function load() {
+        if (destroyed || !checked)
+            return;
+        loadController?.abort();
+        moreController?.abort();
+        const controller = new AbortController();
+        loadController = controller;
+        const hasRows = base.length > 0;
+        commit({
+            status: hasRows ? (state.status === 'error' ? 'loading' : 'ready') : 'loading',
+            refreshing: hasRows,
+            loadingMore: false,
+            moreError: null,
+        });
+        const result = await loader.list(name, checked, { signal: controller.signal, fresh: hasRows });
+        if (controller !== loadController || destroyed)
+            return;
+        loadController = null;
+        if (!result.ok) {
+            if (result.error.code === 'aborted')
+                return;
+            commit({ status: 'error', error: result.error, refreshing: false });
+            return;
+        }
+        base = result.value.rows;
+        applyPage(result.value);
+        commit({
+            status: 'ready',
+            error: null,
+            refreshing: false,
+            hasMore: result.value.hasMore,
+            total: result.value.total,
+        });
+    }
+    async function loadMore() {
+        if (destroyed || !checked || !state.hasMore || state.loadingMore || state.status !== 'ready')
+            return;
+        const controller = new AbortController();
+        moreController = controller;
+        commit({ loadingMore: true, moreError: null });
+        const result = await loader.list(name, checked, {
+            signal: controller.signal,
+            ...(nextCursor === null ? {} : { cursor: nextCursor }),
+            ...(nextOffset === null ? {} : { offset: nextOffset }),
+        });
+        if (controller !== moreController || destroyed)
+            return;
+        moreController = null;
+        if (!result.ok) {
+            if (result.error.code === 'aborted')
+                return;
+            commit({ loadingMore: false, moreError: result.error });
+            return;
+        }
+        // A row that shifted into the next page while paging is shown once.
+        const known = new Set(base.map((row) => `${typeof row[key]}:${String(row[key])}`));
+        const fresh = result.value.rows.filter((row) => !known.has(`${typeof row[key]}:${String(row[key])}`));
+        base = Object.freeze([...base, ...fresh]);
+        applyPage(result.value);
+        commit({
+            loadingMore: false,
+            hasMore: result.value.hasMore,
+            total: result.value.total ?? state.total,
+        });
+    }
+    async function mutate(write, run, settle) {
+        if (destroyed || !descriptor) {
+            return { ok: false, error: state.error ?? sourceError('failed', { source: name }) };
+        }
+        pending = [...pending, write];
+        commit({ writeError: null });
+        const controller = new AbortController();
+        writeControllers.add(controller);
+        const result = await run(controller.signal);
+        writeControllers.delete(controller);
+        pending = pending.filter((entry) => entry !== write);
+        if (destroyed)
+            return result;
+        if (result.ok) {
+            settle(result.value);
+            commit({});
+        }
+        else {
+            // Dropping the pending write is the rollback.
+            commit({ writeError: result.error });
+        }
+        return result;
+    }
+    const collection = {
+        get state() {
+            return state;
+        },
+        descriptor,
+        query: checked,
+        load,
+        loadMore,
+        retry() {
+            if (state.status === 'error')
+                return load();
+            if (state.moreError)
+                return loadMore();
+            return Promise.resolve();
+        },
+        update(id, changes) {
+            seq += 1;
+            const write = { seq, kind: 'update', id, changes: Object.freeze({ ...changes }) };
+            return mutate(write, (signal) => loader.update(name, id, changes, { signal, origin }), (row) => {
+                base = Object.freeze(base.map((existing) => same(existing, id) ? project(row, existing, checked?.fields, key) : existing));
+            });
+        },
+        create(values) {
+            seq += 1;
+            const temp = Object.freeze({ ...values, [key]: `${PENDING_ROW_PREFIX}${seq}` });
+            const write = { seq, kind: 'create', row: temp };
+            return mutate(write, (signal) => loader.create(name, values, { signal, origin }), (row) => {
+                if (base.some((existing) => same(existing, row[key])))
+                    return;
+                const added = project(row, undefined, checked?.fields, key);
+                base = Object.freeze(options.createAt === 'start' ? [added, ...base] : [...base, added]);
+            });
+        },
+        remove(id) {
+            seq += 1;
+            const write = { seq, kind: 'remove', id };
+            return mutate(write, (signal) => loader.remove(name, id, { signal, origin }), () => {
+                base = Object.freeze(base.filter((existing) => !same(existing, id)));
+            });
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            unsubscribe();
+            loadController?.abort();
+            moreController?.abort();
+            for (const controller of writeControllers)
+                controller.abort();
+            writeControllers.clear();
+            listeners.clear();
+        },
+    };
+    // Another view's write to this source reloads this one; this view's own writes do not.
+    const unsubscribe = options.autoRefresh === false || !descriptor
+        ? () => { }
+        : loader.subscribe(name, (event) => {
+            if (event.origin !== origin && state.status !== 'idle')
+                void load();
+        });
+    return Object.freeze(collection);
+}

package/dist/data-source/errors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The typed error model of data sources. Every failure is a `SourceError`
+ * with a closed code, a `retryable` flag and a user-facing `messageKey`;
+ * its `message` is for developers and is never shown to people. Adapters
+ * throw `sourceError(code)` to say what went wrong; anything else they
+ * throw becomes `failed` (not retryable), and its text stays in `cause`.
+ */
+import type { SourceQueryIssue } from './query.js';
+export declare const SOURCE_ERROR_CODES: readonly ["unknown-source", "unsupported", "invalid-query", "invalid-input", "invalid-response", "not-found", "conflict", "unauthorized", "forbidden", "rate-limited", "timeout", "network", "unavailable", "aborted", "failed"];
+export type SourceErrorCode = (typeof SOURCE_ERROR_CODES)[number];
+/** Codes a retry may fix. The loader retries these with backoff (reads only). */
+export declare const RETRYABLE_SOURCE_ERRORS: readonly SourceErrorCode[];
+/**
+ * Codes that describe the view's own request (a source the host never
+ * registered, a refused query or input, a cancelled call): asking again
+ * cannot help, so a view offers no retry for them.
+ */
+export declare const FINAL_SOURCE_ERRORS: readonly SourceErrorCode[];
+/** Whether a person asking again may help (a retry button), unlike `retryable` (automatic retries). */
+export declare function canRetrySourceError(error: Pick<SourceError, 'code'>): boolean;
+/** The i18n key of an error's user-facing message: `dataSource.error.<code>`. */
+export type SourceErrorMessageKey = `dataSource.error.${SourceErrorCode}`;
+export interface SourceError extends Error {
+    readonly name: 'SourceError';
+    readonly code: SourceErrorCode;
+    readonly retryable: boolean;
+    readonly messageKey: SourceErrorMessageKey;
+    /** The source the operation addressed, when known. */
+    readonly source?: string;
+    /** Query or input issues (`invalid-query`, `invalid-input`). */
+    readonly issues?: readonly SourceQueryIssue[];
+    /** A server's retry hint for `rate-limited` or `unavailable`, in milliseconds. */
+    readonly retryAfterMs?: number;
+}
+/** English defaults for every message key; hosts translate by key. */
+export declare const SOURCE_ERROR_MESSAGES: Readonly<Record<SourceErrorMessageKey, string>>;
+export interface SourceErrorInit {
+    /** Developer-facing detail. Never shown to people. */
+    message?: string;
+    /** Overrides the code's default (`RETRYABLE_SOURCE_ERRORS`). */
+    retryable?: boolean;
+    source?: string;
+    issues?: readonly SourceQueryIssue[];
+    retryAfterMs?: number;
+    cause?: unknown;
+}
+/** Make a typed source error. Adapters throw these; the loader recognizes only these. */
+export declare function sourceError(code: SourceErrorCode, init?: SourceErrorInit): SourceError;
+/** Whether `value` was made by {@link sourceError} (a look-alike object is not). */
+export declare function isSourceError(value: unknown): value is SourceError;
+/**
+ * Whatever an adapter threw, as a source error: a `sourceError` keeps its
+ * code (and gains the source name), an `AbortError` is `aborted`, and
+ * anything else is `failed` with the original in `cause`.
+ */
+export declare function toSourceError(thrown: unknown, source?: string): SourceError;
+/** The user-facing English default of an error (hosts translate `messageKey` instead). */
+export declare function sourceErrorMessage(error: Pick<SourceError, 'messageKey'>, messages?: Partial<Record<SourceErrorMessageKey, string>>): string;

package/dist/data-source/errors.js

@@ -0,0 +1,138 @@
+/**
+ * The typed error model of data sources. Every failure is a `SourceError`
+ * with a closed code, a `retryable` flag and a user-facing `messageKey`;
+ * its `message` is for developers and is never shown to people. Adapters
+ * throw `sourceError(code)` to say what went wrong; anything else they
+ * throw becomes `failed` (not retryable), and its text stays in `cause`.
+ */
+export const SOURCE_ERROR_CODES = [
+    'unknown-source',
+    'unsupported',
+    'invalid-query',
+    'invalid-input',
+    'invalid-response',
+    'not-found',
+    'conflict',
+    'unauthorized',
+    'forbidden',
+    'rate-limited',
+    'timeout',
+    'network',
+    'unavailable',
+    'aborted',
+    'failed',
+];
+/** Codes a retry may fix. The loader retries these with backoff (reads only). */
+export const RETRYABLE_SOURCE_ERRORS = Object.freeze([
+    'rate-limited',
+    'timeout',
+    'network',
+    'unavailable',
+]);
+/**
+ * Codes that describe the view's own request (a source the host never
+ * registered, a refused query or input, a cancelled call): asking again
+ * cannot help, so a view offers no retry for them.
+ */
+export const FINAL_SOURCE_ERRORS = Object.freeze([
+    'unknown-source',
+    'unsupported',
+    'invalid-query',
+    'invalid-input',
+    'aborted',
+]);
+/** Whether a person asking again may help (a retry button), unlike `retryable` (automatic retries). */
+export function canRetrySourceError(error) {
+    return !FINAL_SOURCE_ERRORS.includes(error.code);
+}
+/** English defaults for every message key; hosts translate by key. */
+export const SOURCE_ERROR_MESSAGES = Object.freeze({
+    'dataSource.error.unknown-source': 'This data is not available here.',
+    'dataSource.error.unsupported': 'This data cannot be changed here.',
+    'dataSource.error.invalid-query': 'This view asks for data in a way the source does not allow.',
+    'dataSource.error.invalid-input': 'Some values are not valid.',
+    'dataSource.error.invalid-response': 'The data that came back could not be read.',
+    'dataSource.error.not-found': 'This item no longer exists.',
+    'dataSource.error.conflict': 'Someone else changed this item. Reload and try again.',
+    'dataSource.error.unauthorized': 'Sign in to see this data.',
+    'dataSource.error.forbidden': 'You do not have access to this data.',
+    'dataSource.error.rate-limited': 'Too many requests. Try again in a moment.',
+    'dataSource.error.timeout': 'Loading took too long.',
+    'dataSource.error.network': 'The connection was lost.',
+    'dataSource.error.unavailable': 'The data source is unavailable right now.',
+    'dataSource.error.aborted': 'Loading was cancelled.',
+    'dataSource.error.failed': 'Something went wrong loading this data.',
+});
+const BRAND = new WeakSet();
+/** Make a typed source error. Adapters throw these; the loader recognizes only these. */
+export function sourceError(code, init = {}) {
+    const known = SOURCE_ERROR_CODES.includes(code);
+    const safe = known ? code : 'failed';
+    const error = new Error(init.message ?? `Data source error: ${safe}.`, {
+        ...(init.cause === undefined ? {} : { cause: init.cause }),
+    });
+    const retryAfter = typeof init.retryAfterMs === 'number' &&
+        Number.isFinite(init.retryAfterMs) &&
+        init.retryAfterMs >= 0
+        ? init.retryAfterMs
+        : undefined;
+    Object.defineProperties(error, {
+        name: { value: 'SourceError', enumerable: false },
+        code: { value: safe, enumerable: true },
+        retryable: {
+            value: init.retryable ?? RETRYABLE_SOURCE_ERRORS.includes(safe),
+            enumerable: true,
+        },
+        messageKey: { value: `dataSource.error.${safe}`, enumerable: true },
+        ...(init.source === undefined ? {} : { source: { value: init.source, enumerable: true } }),
+        ...(init.issues === undefined
+            ? {}
+            : { issues: { value: Object.freeze([...init.issues]), enumerable: true } }),
+        ...(retryAfter === undefined ? {} : { retryAfterMs: { value: retryAfter, enumerable: true } }),
+    });
+    BRAND.add(error);
+    return Object.freeze(error);
+}
+/** Whether `value` was made by {@link sourceError} (a look-alike object is not). */
+export function isSourceError(value) {
+    return typeof value === 'object' && value !== null && BRAND.has(value);
+}
+function isAbort(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.name === 'AbortError');
+}
+/**
+ * Whatever an adapter threw, as a source error: a `sourceError` keeps its
+ * code (and gains the source name), an `AbortError` is `aborted`, and
+ * anything else is `failed` with the original in `cause`.
+ */
+export function toSourceError(thrown, source) {
+    if (isSourceError(thrown)) {
+        if (source === undefined || thrown.source !== undefined)
+            return thrown;
+        return sourceError(thrown.code, {
+            message: thrown.message,
+            retryable: thrown.retryable,
+            source,
+            ...(thrown.issues ? { issues: thrown.issues } : {}),
+            ...(thrown.retryAfterMs === undefined ? {} : { retryAfterMs: thrown.retryAfterMs }),
+            cause: thrown.cause,
+        });
+    }
+    if (isAbort(thrown)) {
+        return sourceError('aborted', { ...(source === undefined ? {} : { source }), cause: thrown });
+    }
+    return sourceError('failed', {
+        message: 'The data source failed.',
+        ...(source === undefined ? {} : { source }),
+        cause: thrown,
+    });
+}
+/** The user-facing English default of an error (hosts translate `messageKey` instead). */
+export function sourceErrorMessage(error, messages = {}) {
+    const key = error.messageKey;
+    return ((Object.hasOwn(messages, key) ? messages[key] : undefined) ??
+        SOURCE_ERROR_MESSAGES[key] ??
+        SOURCE_ERROR_MESSAGES['dataSource.error.failed']);
+}

package/dist/data-source/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @texuli/core/data-source: host-registered data sources for generated
+ * views (ADR-015). The host declares each source (typed fields, the
+ * operations, filter and sort capabilities, pagination) and writes its
+ * adapter; a blueprint names a source and sends a closed query. The loader
+ * validates, deduplicates, cancels, retries, caches and invalidates; a
+ * collection pages and applies optimistic writes with rollback. Errors are
+ * typed, with a retryable flag and a user-facing message key.
+ *
+ * Framework-free and not re-exported from the `@texuli/core` root barrel.
+ */
+export { createSourceCollection, PENDING_ROW_PREFIX, type SourceCollection, type SourceCollectionOptions, type SourceCollectionState, type SourceCollectionStatus, } from './collection.js';
+export { canRetrySourceError, FINAL_SOURCE_ERRORS, isSourceError, RETRYABLE_SOURCE_ERRORS, SOURCE_ERROR_CODES, SOURCE_ERROR_MESSAGES, type SourceError, type SourceErrorCode, type SourceErrorInit, type SourceErrorMessageKey, sourceError, sourceErrorMessage, toSourceError, } from './errors.js';
+export { createSourceLoader, DEFAULT_SOURCE_RETRY, isSourceRowId, MAX_RETRY_AFTER_MS, readSourceRow, type SourceCallOptions, type SourceClock, type SourceInvalidation, type SourceListOptions, type SourceListResult, type SourceLoader, type SourceLoaderOptions, type SourceMutationOptions, type SourceQueryResolution, type SourceResult, type SourceRetryPolicy, SYSTEM_SOURCE_CLOCK, } from './loader.js';
+export { checkSourceQuery, fitsSourceField, isSourceDate, SOURCE_QUERY_KEYS, type SourceFilterCondition, type SourceFilterGroup, type SourceFilterNode, type SourceQuery, type SourceQueryCheck, type SourceQueryIssue, type SourceQueryIssueCode, type SourceSort, type SourceValue, sourceQueryKey, stableJson, } from './query.js';
+export { createSourceRegistry, type DataSource, defineSource, type SourceAdapter, type SourceListRequest, type SourcePage, type SourcePageRequest, type SourceRegistry, type SourceRow, type SourceRowId, } from './registry.js';
+export { describeSource, isSourceFieldName, isSourceName, SOURCE_FIELD_PATTERN, SOURCE_FIELD_TYPES, SOURCE_FILTER_OPERATORS, SOURCE_LIMITS, SOURCE_NAME_PATTERN, SOURCE_OPERATIONS, SOURCE_OPERATORS_BY_TYPE, SOURCE_PAGINATION_STYLES, type SourceDescriptor, type SourceFieldDeclaration, type SourceFieldDescriptor, type SourceFieldType, type SourceFilterOperator, type SourceOperation, type SourcePaginationStyle, type SourceSchemaDeclaration, sourceField, } from './schema.js';

package/dist/data-source/index.js

@@ -0,0 +1,17 @@
+/**
+ * @texuli/core/data-source: host-registered data sources for generated
+ * views (ADR-015). The host declares each source (typed fields, the
+ * operations, filter and sort capabilities, pagination) and writes its
+ * adapter; a blueprint names a source and sends a closed query. The loader
+ * validates, deduplicates, cancels, retries, caches and invalidates; a
+ * collection pages and applies optimistic writes with rollback. Errors are
+ * typed, with a retryable flag and a user-facing message key.
+ *
+ * Framework-free and not re-exported from the `@texuli/core` root barrel.
+ */
+export { createSourceCollection, PENDING_ROW_PREFIX, } from "./collection.js";
+export { canRetrySourceError, FINAL_SOURCE_ERRORS, isSourceError, RETRYABLE_SOURCE_ERRORS, SOURCE_ERROR_CODES, SOURCE_ERROR_MESSAGES, sourceError, sourceErrorMessage, toSourceError, } from "./errors.js";
+export { createSourceLoader, DEFAULT_SOURCE_RETRY, isSourceRowId, MAX_RETRY_AFTER_MS, readSourceRow, SYSTEM_SOURCE_CLOCK, } from "./loader.js";
+export { checkSourceQuery, fitsSourceField, isSourceDate, SOURCE_QUERY_KEYS, sourceQueryKey, stableJson, } from "./query.js";
+export { createSourceRegistry, defineSource, } from "./registry.js";
+export { describeSource, isSourceFieldName, isSourceName, SOURCE_FIELD_PATTERN, SOURCE_FIELD_TYPES, SOURCE_FILTER_OPERATORS, SOURCE_LIMITS, SOURCE_NAME_PATTERN, SOURCE_OPERATIONS, SOURCE_OPERATORS_BY_TYPE, SOURCE_PAGINATION_STYLES, sourceField, } from "./schema.js";