@byline/core 3.20.4 → 4.0.0

package/dist/@types/collection-types.d.ts

@@ -124,10 +124,10 @@ export interface UploadConfig {
      * have been written to the storage provider, before the document
      * version is created.
      *
-     * Accepts an inline object, or — because the schema is isomorphic — a
-     * **loader** (`hooks: () => import('./media.hooks.js')`) that defers the
-     * hooks module so server-only code (storage SDKs, `sharp`, AV scanners)
-     * never enters the client bundle. See {@link UploadHooksLoader}.
+     * Accepts an inline object or a lazy loader. Both remain reachable from an
+     * isomorphic schema, so use them only for isomorphic-safe hooks. Hooks that
+     * import server-only code belong in `ServerConfig.hooks.uploads`, registered
+     * from the server entry. See {@link UploadHooksLoader}.
      *
      * @see UploadHooks
      */
@@ -461,6 +461,32 @@ export interface AfterUpdateContext {
         locale: string;
     };
 }
+/**
+ * Context passed to `afterSystemFieldsChange` after a non-versioned document
+ * path and/or advertised-locale change commits successfully.
+ *
+ * Both snapshots are included so cache and search consumers can remove stale
+ * paths and reconcile locale-specific output without re-reading the old state.
+ */
+export interface SystemFieldsChangeContext {
+    documentId: string;
+    collectionPath: string;
+    /** Fields explicitly supplied by the caller, including a no-op retry. */
+    requested: {
+        path: boolean;
+        availableLocales: boolean;
+    };
+    changed: {
+        path: boolean;
+        availableLocales: boolean;
+    };
+    /** True when a no-op request deliberately re-runs post-commit reconciliation. */
+    reconciliation: boolean;
+    previousPath?: string;
+    currentPath?: string;
+    previousAvailableLocales: string[];
+    currentAvailableLocales: string[];
+}
 /**
  * Context passed to `beforeStatusChange` / `afterStatusChange` hooks.
  *
@@ -700,16 +726,13 @@ export interface UploadHooks {
  * `() => import('./media.hooks.js')` works directly against an
  * `export default { … } satisfies UploadHooks`).
  *
- * Same rationale as {@link CollectionHooksLoader}: upload hooks are declared
- * on a field *inside the collection schema*, which is **isomorphic** (bundled
- * into the client admin). `beforeStore` / `afterStore` bodies typically reach
- * for server-only code — storage SDKs, `sharp`, AV scanners, `node:crypto` —
- * so declaring them inline drags that graph into the client bundle. The
- * loader form defers the hooks module behind a dynamic `import()`, keeping it
- * structurally absent from the client.
+ * For hooks that are safe in both browser and server graphs, schemas may use
+ * this loader form directly. A dynamic import in an isomorphic schema is not
+ * by itself a client boundary: server-only hook modules must instead be
+ * registered through `ServerConfig.hooks.uploads`, from a server-only entry.
  *
  * @example
- * // media.schema.ts — isomorphic, client-safe by construction
+ * // media.schema.ts — only for isomorphic-safe hooks
  * {
  *   name: 'image',
  *   type: 'image',
@@ -719,7 +742,7 @@ export interface UploadHooks {
  *   },
  * }
  *
- * // media.hooks.ts — server-only; may import any server-only module freely
+ * // media.hooks.ts — must remain safe for every graph that imports the schema
  * export default { afterStore: (ctx) => { … } } satisfies UploadHooks
  */
 export type UploadHooksLoader = () => Promise<UploadHooks | {
@@ -747,12 +770,15 @@ export declare function resolveUploadHooks(hooks: UploadHooks | UploadHooksLoade
  *   - `find`, `findOne`, `findById`, `findByPath` on `CollectionHandle`
  *     (once per returned source document)
  *   - Each populated relation target across every depth level
+ *   - Rich-text targets, tree/search hydration, and historical versions
  *
  * The hook receives the **raw storage shape** (`{document_version_id,
  * document_id, path, status, created_at, updated_at, fields, …}`), not
  * the camelCase `ClientDocument` — afterRead runs *before* the client's
  * response shaping pass so mutations to `fields` propagate cleanly.
  * Mutations persist in place; there is no return value.
+ * `requestContext` is the immutable operation-scoped identity and effective
+ * read mode, enabling actor-dependent field redaction on every path.
  *
  * Fires **after** populate on the source document, so hooks can observe
  * (and mutate) the fully populated tree.
@@ -767,6 +793,8 @@ export interface AfterReadContext {
     /** The raw reconstructed document. Mutate in place — changes persist. */
     doc: Record<string, any>;
     collectionPath: string;
+    /** Authenticated identity cloned for this operation's effective read mode. */
+    requestContext: RequestContext;
     /** Thread this into any nested reads the hook performs. */
     readContext: ReadContext;
 }
@@ -780,10 +808,10 @@ export interface AfterReadContext {
  * emits, then ANDs onto whatever the caller passed in `where`.
  *
  * Returning `undefined` (or simply `void`) means "no scoping" — typically
- * the superuser / unconditional-read branch. Use a sentinel predicate that
- * yields no rows (e.g. `{ id: '__none__' }`) when the actor cannot read
- * anything; do not throw, because callers expect empty list results rather
- * than collapsed endpoints.
+ * the superuser / unconditional-read branch. Return `{ id: { $in: [] } }`
+ * when the actor cannot read anything; it compiles to an always-false SQL
+ * predicate without passing an invalid UUID to Postgres. Do not throw, because
+ * callers expect empty list results rather than collapsed endpoints.
  *
  * The hook receives:
  *   - `requestContext` — the authenticated request, including `actor`. The
@@ -853,6 +881,13 @@ export interface CollectionHooks {
     beforeUpdate?: CollectionHookSlot<BeforeUpdateContext>;
     /** Runs after an existing document is updated. */
     afterUpdate?: CollectionHookSlot<AfterUpdateContext>;
+    /**
+     * Runs after an actual path and/or advertised-locale change commits, or for
+     * an explicit no-op reconciliation retry. A failure rejects the lifecycle
+     * call but cannot roll back the already-committed system-field write/audit;
+     * retry with reconciliation enabled to run post-commit side effects again.
+     */
+    afterSystemFieldsChange?: CollectionHookSlot<SystemFieldsChangeContext>;
     /** Runs before a document's workflow status is changed. */
     beforeStatusChange?: CollectionHookSlot<StatusChangeContext>;
     /** Runs after a document's workflow status has been changed. */
@@ -902,23 +937,20 @@ export interface CollectionHooks {
  * (so `() => import('./docs.hooks.js')` works directly against an
  * `export default { … } satisfies CollectionHooks`).
  *
- * Why this exists: a `CollectionDefinition` is **isomorphic** — the same
- * schema module is bundled into the *client* admin as well as the server.
- * Any module the schema *statically imports* is dragged into the client
- * bundle, so a hook body that imports server-only code (cache invalidation,
- * queue clients, Node built-ins) leaks that entire graph into the browser.
- * The loader form defers the hooks module behind a dynamic `import()`, so
- * the hooks module and its server-only graph are *structurally absent* from
- * the client — no per-call-site SSR guards required.
+ * A loader attached directly to an isomorphic schema is suitable only when
+ * its hook module is safe in every graph that imports that schema. Dynamic
+ * imports may still become browser chunks. Register hooks that import
+ * server-only code through `ServerConfig.hooks.collections` from a server-only
+ * entry instead.
  *
  * @example
- * // docs.schema.ts — isomorphic, client-safe by construction
+ * // docs.schema.ts — only for isomorphic-safe hooks
  * export const Docs = defineCollection({
  *   // …declarative field config…
  *   hooks: () => import('./docs.hooks.js'),
  * })
  *
- * // docs.hooks.ts — server-only; may import any server-only module freely
+ * // docs.hooks.ts — must remain safe for every graph that imports the schema
  * import { invalidateDocument } from '@/lib/cache/with-cache'
  * export default {
  *   afterCreate: ({ collectionPath, path }) => invalidateDocument(collectionPath, path),
@@ -972,12 +1004,15 @@ export interface CollectionDefinition {
     /**
      * Lifecycle hooks for server-side document operations.
      *
-     * Two forms:
+     * Two definition-attached forms:
      * - **Inline** (`hooks: { afterCreate, … }`) — valid for hooks whose
      *   bodies only touch isomorphic / declarative code.
-     * - **Loader** (`hooks: () => import('./docs.hooks.js')`) — defers the
-     *   hooks module behind a dynamic `import()` so server-only code never
-     *   enters the client bundle. See {@link CollectionHooksLoader}.
+     * - **Loader** (`hooks: () => import('./docs.hooks.js')`) — lazy, but still
+     *   part of the schema's reachable module graph. See
+     *   {@link CollectionHooksLoader}.
+     *
+     * Hooks that import server-only modules belong in
+     * `ServerConfig.hooks.collections`, registered from the server entry.
      */
     hooks?: CollectionHooks | CollectionHooksLoader;
     /**
@@ -1187,6 +1222,12 @@ export interface CollectionDefinition {
 export declare function defineCollection<const C extends CollectionDefinition>(definition: C & CollectionDefinition): C;
 export type CollectionFieldData<C extends CollectionDefinition> = FieldSetData<C['fields']>;
 export type CollectionFieldDataAllLocales<C extends CollectionDefinition> = FieldSetDataAllLocales<C['fields']>;
+/** Broad collection registry used when an application has not supplied its schema types. */
+export type CollectionRegistry = Record<string, Record<string, any>>;
+/** Infer a path-to-fields registry from a shared readonly collection-definition tuple. */
+export type InferCollectionRegistry<TCollections extends readonly CollectionDefinition[]> = {
+    [TCollection in TCollections[number] as TCollection['path']]: CollectionFieldData<TCollection>;
+};
 /**
  * Type-safe factory for creating a Block. Returns the definition as-is,
  * but locks in literal types for `blockType`, field names, and select

package/dist/@types/db-types.d.ts

@@ -61,24 +61,10 @@ export interface ReadContext {
      */
     visited: Set<string>;
     /**
-     * Composite keys (`${collection_path}:${document_id}`) for every
-     * document whose `afterRead` hook has fired during this request. Used
-     * to enforce "each document runs through `afterRead` at most once per
-     * logical request" — the rule that forecloses the A→B→A loop when a
-     * hook performs its own reads.
+     * @deprecated Ignored. `beforeRead` authorization state is module-private
+     * and authority-bound; this optional slot remains only for source compatibility.
      */
-    afterReadFired: Set<string>;
-    /**
-     * Per-request memoisation of `beforeRead` hook results, keyed by
-     * `collectionPath`. Populate fans out across many source documents and
-     * many target-collection batches; without a cache, an async hook
-     * (e.g. resolving the actor's tenant id) would re-run on every batch.
-     * Keyed by collection path because the actor is invariant for the
-     * lifetime of one `ReadContext`. `null` records "hook ran and returned
-     * void" (i.e. no scoping applies); absence records "hook has not been
-     * run yet for this collection".
-     */
-    beforeReadCache: Map<string, QueryPredicate | null>;
+    beforeReadCache?: Map<string, QueryPredicate | null>;
     /** Monotonic count of document materialisations; compared against `maxReads`. */
     readCount: number;
     /** Hard ceiling on materialisations per request. Default 500. */
@@ -225,39 +211,28 @@ export interface IDbAdapter {
         collections: ICollectionCommands;
         documents: IDocumentCommands;
         counters: ICounterCommands;
-        /**
-         * Append-only audit-log writes (docs/06-auth-and-security/02-auditability.md — Workstream 2). Optional
-         * capability, paired with `withTransaction`: a consumer that records audit
-         * entries asserts both are present and throws otherwise (it must never
-         * silently skip the audit row). Adapters that model the audit log
-         * implement it; others omit it.
-         */
-        audit?: IAuditCommands;
+        /** Append-only audit-log writes, committed atomically via `withTransaction`. */
+        audit: IAuditCommands;
     };
     queries: {
         collections: ICollectionQueries;
         documents: IDocumentQueries;
-        /** Audit-log reads — per-document history, system-wide report. See docs/06-auth-and-security/02-auditability.md. */
-        audit?: IAuditQueries;
+        /** Audit-log reads — per-document history, system-wide report. */
+        audit: IAuditQueries;
     };
     /**
-     * Optional capability: run `fn` inside a single database transaction so the
+     * Run `fn` inside a single database transaction so the
      * writes it performs commit or roll back atomically. The adapter propagates
      * the transaction to every `commands.*` call made within `fn` (see
      * docs/03-architecture/03-transactions.md — AsyncLocalStorage propagation), so a service can
      * compose multiple commands into one unit of work without threading a
      * transaction handle through their signatures.
      *
-     * **Loud-failure contract.** Optional because not every adapter can provide
-     * interactive transactions — a pure HTTP-gateway serverless driver (Neon
-     * HTTP, Cloudflare D1, …) cannot. An adapter that cannot **must omit this
-     * method** (or implement it to throw); a consumer that requires atomicity
-     * (e.g. the audit log) MUST assert its presence and throw — never silently
-     * run non-atomically, which would defeat the very guarantee it provides. See
-     * docs/03-architecture/03-transactions.md ("Serverless / HTTP-gateway databases — the contract
-     * seam").
+     * Canonical adapters must provide interactive transactions because audited
+     * lifecycle mutations cannot safely degrade to non-atomic writes. Runtime
+     * lifecycle guards remain in place for untyped JavaScript adapters.
      */
-    withTransaction?: <T>(fn: () => Promise<T>) => Promise<T>;
+    withTransaction: <T>(fn: () => Promise<T>) => Promise<T>;
     /**
      * Optional maintenance: stamp `source_locale` (the per-document content
      * anchor) on documents created before the column existed, setting NULL rows
@@ -474,6 +449,34 @@ export interface ICollectionCommands {
     }): Promise<any>;
     delete(id: string): Promise<any>;
 }
+/** Locked structural state returned by tree mutation commands. */
+export interface TreePlacementState {
+    placed: boolean;
+    parentDocumentId: string | null;
+    orderKey: string | null;
+    index: number | null;
+}
+/** Result of an atomic place/reorder/remove tree command. */
+export interface TreeMutationResult {
+    changed: boolean;
+    before: TreePlacementState;
+    after: TreePlacementState;
+    /** The pre-mutation sibling group, used only for post-commit hook fan-out. */
+    beforeSiblingDocumentIds: string[];
+    /** Locked pre-mutation node + descendants, populated when requested for hooks. */
+    beforeSubtreeDocumentIds: string[];
+}
+/** One child promoted to root while deleting its parent. */
+export interface TreePromotionChange {
+    documentId: string;
+    before: TreePlacementState;
+    after: TreePlacementState;
+}
+/** Atomic edge reconciliation performed as part of document deletion. */
+export interface TreeDeleteMutationResult {
+    removed: TreeMutationResult;
+    promoted: TreePromotionChange[];
+}
 export interface IDocumentCommands {
     createDocumentVersion(params: {
         documentId?: string;
@@ -654,9 +657,9 @@ export interface IDocumentCommands {
         parentDocumentId: string | null;
         beforeDocumentId?: string | null;
         afterDocumentId?: string | null;
-    }): Promise<{
-        orderKey: string;
-    }>;
+        /** Internal create/self-heal guard: leave an already-placed node untouched. */
+        ifUnplaced?: boolean;
+    }): Promise<TreeMutationResult>;
     /**
      * Remove a document's edge row, returning it to the *unplaced* state (in the
      * collection, but not in the tree). Distinct from document deletion — the
@@ -664,8 +667,21 @@ export interface IDocumentCommands {
      * unplaced. See docs/04-collections/03-document-trees.md.
      */
     removeFromTree(params: {
+        collectionId: string;
         documentId: string;
-    }): Promise<void>;
+        /** Capture the authoritative pre-removal subtree under the tree lock. */
+        includeSubtree?: boolean;
+    }): Promise<TreeMutationResult>;
+    /**
+     * Atomically promote a node's direct children to roots and remove its edge,
+     * returning locked before/after states for parent and child audit rows. This
+     * capability is required by the canonical adapter contract and is also
+     * validated at runtime for untyped JavaScript adapters.
+     */
+    promoteChildrenAndRemoveFromTree(params: {
+        collectionId: string;
+        documentId: string;
+    }): Promise<TreeDeleteMutationResult>;
 }
 export interface ICollectionQueries {
     getAllCollections(): Promise<any[]>;
@@ -673,6 +689,20 @@ export interface ICollectionQueries {
     getCollectionById(id: string): Promise<any>;
 }
 export interface IDocumentQueries {
+    /**
+     * Lock a logical document as the transaction mutex for its non-versioned
+     * system fields, then return their authoritative current values. Must be
+     * called inside `IDbAdapter.withTransaction`. Canonical adapters must support
+     * this locked read so system-field audit rows use an authoritative snapshot.
+     */
+    getDocumentSystemFieldsForUpdate(params: {
+        collection_id: string;
+        document_id: string;
+    }): Promise<{
+        source_locale: string;
+        path: string | null;
+        availableLocales: string[];
+    } | null>;
     getDocumentById(params: {
         collection_id: string;
         document_id: string;
@@ -771,7 +801,11 @@ export interface IDocumentQueries {
     getDocumentByVersion(params: {
         document_version_id: string;
         locale?: string;
-    }): Promise<any>;
+        /** Optional collection ownership gate for client-facing historical reads. */
+        collection_id?: string;
+        /** Historical-row `beforeRead` predicates compiled against this version. */
+        filters?: DocumentFilter[];
+    }): Promise<any | null>;
     getDocumentsByVersionIds(params: {
         document_version_ids: string[];
         locale?: string;
@@ -809,6 +843,8 @@ export interface IDocumentQueries {
         order?: string;
         desc?: boolean;
         query?: string;
+        /** Historical-row `beforeRead` predicates applied before count/pagination. */
+        filters?: DocumentFilter[];
     }): Promise<{
         documents: any[];
         meta: {
@@ -981,14 +1017,16 @@ export interface IDocumentQueries {
      * unpublished ancestor** — it does *not* skip past it. So an unpublished
      * mid-spine node truncates the returned chain, which the hierarchical-URL
      * splat handler turns into a 404 (the "unpublished node hides its subtree"
-     * decision, enforced at the URL layer). `readMode: 'any'` (the default) walks
-     * the raw edges, matching the breadcrumb/lifecycle use that wants every
-     * ancestor regardless of status.
+     * decision, enforced at the URL layer). Optional `filters` apply the same
+     * edge rule for `beforeRead`, including visibility of the queried node.
+     * `readMode: 'any'` (the default) otherwise walks current non-deleted rows.
      */
     getTreeAncestors(params: {
         document_id: string;
         maxDepth?: number;
         readMode?: ReadMode;
+        locale?: string;
+        filters?: DocumentFilter[];
     }): Promise<Array<{
         document_id: string;
         depth: number;
@@ -1018,13 +1056,18 @@ export interface IDocumentQueries {
      * `getTreeAncestors` returns `[]` for *both* a root and an unplaced node, so it
      * cannot tell them apart; this primitive can. Backs the update-time self-heal
      * (re-root a stray doc) and the authoring widget's "Add to tree" vs "Top level"
-     * distinction.
+     * distinction. With visibility filters, a hidden queried node reports
+     * unplaced; a hidden parent is redacted to null while `placed` remains true.
      */
     getTreeParent(params: {
         document_id: string;
+        readMode?: ReadMode;
+        locale?: string;
+        filters?: DocumentFilter[];
     }): Promise<{
         placed: boolean;
         parentDocumentId: string | null;
+        parentRedacted?: true;
     }>;
     /**
      * Read a node's subtree as a flat, **pre-order (depth-first)** list — each
@@ -1043,7 +1086,8 @@ export interface IDocumentQueries {
      * nodes, an unpublished node's entire subtree is omitted — the spine is
      * broken and descendants are not promoted (see docs/04-collections/03-document-trees.md).
      * `readMode: 'any'` (the default) includes every current, non-deleted node.
-     * Depth-bounded by `maxDepth` as a backstop.
+     * Optional `filters` enforce `beforeRead` at every edge with the same
+     * no-promotion semantics. Depth-bounded by `maxDepth` as a backstop.
      *
      * Returns structure only; hydrate content via `getDocumentsByDocumentIds`.
      */
@@ -1052,6 +1096,8 @@ export interface IDocumentQueries {
         rootDocumentId?: string | null;
         maxDepth?: number;
         readMode?: ReadMode;
+        locale?: string;
+        filters?: DocumentFilter[];
     }): Promise<Array<{
         document_id: string;
         parent_document_id: string | null;

package/dist/@types/field-data-types.d.ts

@@ -5,7 +5,8 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { ArrayField, BlocksField, Field, FieldSet, GroupField, LocalizedField, OptionalField, SelectField } from './field-types.js';
+import type { ArrayField, BlocksField, Field, FieldSet, GroupField, LocalizedField, OptionalField, RelationField, SelectField } from './field-types.js';
+import type { RelatedDocumentValue } from './relation-types.js';
 import type { Prettify, ValueUnion } from './type-utils.js';
 /**
  * Structural type for any JSON-serializable value. Used as the type for
@@ -55,9 +56,12 @@ type BlocksFieldData<T extends BlocksField> = Array<Prettify<ValueUnion<{
         _type: K['blockType'];
     } & FieldSetData<K['fields']>>;
 }>>>;
+type RelationFieldData<T extends RelationField> = T extends {
+    hasMany: true;
+} ? RelatedDocumentValue[] : RelatedDocumentValue;
 type BaseFieldData<T extends Field> = T extends ArrayField ? Array<Prettify<{
     _id: string;
-} & FieldSetData<T['fields']>>> : T extends BlocksField ? Prettify<BlocksFieldData<T>> : T extends GroupField ? FieldSetData<T['fields']> : T extends SelectField ? T['options'][number]['value'] : BaseFieldDataTypes[T['type']];
+} & FieldSetData<T['fields']>>> : T extends BlocksField ? Prettify<BlocksFieldData<T>> : T extends GroupField ? FieldSetData<T['fields']> : T extends SelectField ? T['options'][number]['value'] : T extends RelationField ? RelationFieldData<T> : BaseFieldDataTypes[T['type']];
 export type FieldData<T extends Field = Field> = T extends OptionalField ? BaseFieldData<T> | undefined : BaseFieldData<T>;
 export type FieldSetData<T extends FieldSet = FieldSet> = Prettify<{
     -readonly [F in T[number] as F extends OptionalField ? never : F['name']]: FieldData<F>;
@@ -75,7 +79,7 @@ type BlocksFieldDataAllLocales<T extends BlocksField> = Array<Prettify<ValueUnio
 }>>>;
 type BaseFieldDataAllLocales<T extends Field> = T extends ArrayField ? Array<Prettify<{
     _id: string;
-} & FieldSetDataAllLocales<T['fields']>>> : T extends BlocksField ? Prettify<BlocksFieldDataAllLocales<T>> : T extends GroupField ? FieldSetDataAllLocales<T['fields']> : T extends SelectField ? T['options'][number]['value'] : BaseFieldDataTypes[T['type']];
+} & FieldSetDataAllLocales<T['fields']>>> : T extends BlocksField ? Prettify<BlocksFieldDataAllLocales<T>> : T extends GroupField ? FieldSetDataAllLocales<T['fields']> : T extends SelectField ? T['options'][number]['value'] : T extends RelationField ? RelationFieldData<T> : BaseFieldDataTypes[T['type']];
 type LocalizedFieldDataAllLocales<T extends Field> = T extends LocalizedField ? PerLocale<BaseFieldDataAllLocales<T>> : BaseFieldDataAllLocales<T>;
 export type FieldDataAllLocales<T extends Field = Field> = T extends OptionalField ? LocalizedFieldDataAllLocales<T> | undefined : LocalizedFieldDataAllLocales<T>;
 export type FieldSetDataAllLocales<T extends FieldSet = FieldSet> = Prettify<{
@@ -135,7 +139,7 @@ export interface PendingStoredFileValue {
     filename: string;
     originalFilename: string;
     mimeType: string;
-    fileSize: string;
+    fileSize: number;
     storageProvider: 'pending';
     storagePath: '';
     storageUrl: string;
@@ -157,10 +161,4 @@ export declare function createPendingStoredFileValue(file: File, previewUrl: str
     width: number;
     height: number;
 }): PendingStoredFileValue;
-export interface RelatedDocumentValue {
-    targetDocumentId: string;
-    targetCollectionId: string;
-    relationshipType?: string;
-    cascadeDelete?: boolean;
-}
 export {};

package/dist/@types/field-data-types.js

@@ -23,7 +23,7 @@ export function createPendingStoredFileValue(file, previewUrl, dimensions) {
         filename: file.name,
         originalFilename: file.name,
         mimeType: file.type,
-        fileSize: String(file.size),
+        fileSize: file.size,
         storageProvider: 'pending',
         storagePath: '',
         storageUrl: previewUrl,

package/dist/@types/field-data-types.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/@types/field-data-types.test.node.js

@@ -0,0 +1,70 @@
+import { File } from 'node:buffer';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { defineCollection } from './collection-types.js';
+import { createPendingStoredFileValue } from './field-data-types.js';
+const RelationShapes = defineCollection({
+    path: 'relation-shapes',
+    labels: { singular: 'Relation shape', plural: 'Relation shapes' },
+    fields: [
+        { name: 'single', type: 'relation', targetCollection: 'people' },
+        { name: 'many', type: 'relation', targetCollection: 'people', hasMany: true },
+        {
+            name: 'group',
+            type: 'group',
+            fields: [
+                { name: 'single', type: 'relation', targetCollection: 'people' },
+                { name: 'many', type: 'relation', targetCollection: 'people', hasMany: true },
+            ],
+        },
+        {
+            name: 'items',
+            type: 'array',
+            fields: [
+                { name: 'single', type: 'relation', targetCollection: 'people' },
+                { name: 'many', type: 'relation', targetCollection: 'people', hasMany: true },
+            ],
+        },
+        {
+            name: 'content',
+            type: 'blocks',
+            blocks: [
+                {
+                    blockType: 'relations',
+                    fields: [
+                        { name: 'single', type: 'relation', targetCollection: 'people' },
+                        { name: 'many', type: 'relation', targetCollection: 'people', hasMany: true },
+                    ],
+                },
+            ],
+        },
+        { name: 'localizedTitle', type: 'text', localized: true },
+    ],
+});
+describe('field data contracts', () => {
+    it('infers single and hasMany relations through nested structures', () => {
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+    });
+    it('keeps a pending file size numeric', () => {
+        const pending = createPendingStoredFileValue(new File(['content'], 'fixture.txt', { type: 'text/plain' }), 'blob:fixture');
+        expect(pending.fileSize).toBe(7);
+        expectTypeOf(pending.fileSize).toEqualTypeOf();
+    });
+    it('exposes generic single and hasMany relation read envelopes', () => {
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+    });
+});

package/dist/@types/field-types.d.ts

@@ -5,7 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import type { RequestContext } from '@byline/auth';
 import type { UploadConfig } from './collection-types.js';
+import type { ReadMode } from './db-types.js';
 import type { MaybePromise, NonEmptyArray } from './type-utils.js';
 /**
  * Context passed to functions that generate default values for fields,
@@ -703,7 +705,7 @@ export type RichTextEditorComponent = SlotComponent<RichTextEditorProps>;
  * Context passed to the richtext populate function for one rich-text field
  * value. Mirrors the shape consumed by the relation-field populate
  * primitive — `readContext` is the same request-scoped context, so the
- * visited set / read budget / `afterReadFired` machinery covers rich-text
+ * visited set / read budget / `afterRead` recursion machinery covers rich-text
  * fan-out automatically and any nested reads the adapter performs.
  *
  * The adapter mutates `value` in place — typically by walking the editor's
@@ -724,7 +726,23 @@ export interface RichTextPopulateContext {
      * read they perform via `_readContext`.
      */
     readContext: import('./db-types.js').ReadContext;
+    /** Authenticated context cloned for this operation's effective read mode. */
+    requestContext: RequestContext;
+    /** Effective source-view selector inherited from the containing read. */
+    readMode: ReadMode;
+    /**
+     * Framework-owned secure target reader. Editor adapters must use this
+     * instead of direct adapter access so target abilities and `beforeRead`
+     * predicates are enforced uniformly.
+     */
+    readDocuments: RichTextReadDocumentsFn;
+}
+export interface RichTextReadDocumentsInput {
+    collectionPath: string;
+    documentIds: string[];
+    fields?: string[];
 }
+export type RichTextReadDocumentsFn = (input: RichTextReadDocumentsInput) => Promise<Array<Record<string, any>>>;
 /**
  * Server-side populate function contract. Editor adapters export an
  * implementation; installations register one via
@@ -760,6 +778,12 @@ export interface RichTextEmbedContext {
      * budget machinery with the rest of the framework.
      */
     readContext: import('./db-types.js').ReadContext;
+    /** Authenticated write-operation context used for target read checks. */
+    requestContext: RequestContext;
+    /** Embed refreshes resolve the public/published target view. */
+    readMode: ReadMode;
+    /** Framework-owned ability- and beforeRead-aware target reader. */
+    readDocuments: RichTextReadDocumentsFn;
 }
 /**
  * Server-side embed function contract. Editor adapters export an

package/dist/@types/index.d.ts

@@ -12,6 +12,7 @@ export * from './field-data-types.js';
 export * from './field-types.js';
 export * from './populate-types.js';
 export * from './query-predicate.js';
+export * from './relation-types.js';
 export * from './search-types.js';
 export * from './site-config.js';
 export * from './storage-types.js';

package/dist/@types/index.js

@@ -12,6 +12,7 @@ export * from './field-data-types.js';
 export * from './field-types.js';
 export * from './populate-types.js';
 export * from './query-predicate.js';
+export * from './relation-types.js';
 export * from './search-types.js';
 export * from './site-config.js';
 export * from './storage-types.js';