@byline/client 3.12.2 → 3.13.0

package/dist/collection-handle.d.ts

@@ -7,7 +7,7 @@
  */
 import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
 import type { BylineClient } from './client.js';
-import type { AuditLogOptions, ClientDocument, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, HistoryOptions, UpdateOptions } from './types.js';
+import type { AuditLogOptions, ClientDocument, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, HistoryOptions, PlaceTreeNodeOptions, TreeNode, UpdateOptions } from './types.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -151,6 +151,52 @@ export declare class CollectionHandle {
      * document. Use `history()` instead if you want the access gate.
      */
     findByVersion<F = Record<string, any>>(versionId: string, options?: FindByVersionOptions<F>): Promise<ClientDocument<F> | null>;
+    /**
+     * Place or move a document within this collection's tree — a single upsert
+     * covering place, reorder, and re-parent (they differ only in whether the
+     * parent changes). Document-grain and unversioned: mints no new document
+     * version and does not touch workflow status. The storage layer enforces the
+     * cycle and same-collection invariants atomically. Returns the minted
+     * per-parent `order_key`.
+     */
+    placeTreeNode(documentId: string, options: PlaceTreeNodeOptions): Promise<{
+        orderKey: string;
+    }>;
+    /**
+     * Remove a document from the tree, returning it to the *unplaced* state (still
+     * in the collection, but not in any table of contents). Distinct from
+     * deleting the document. No-op when already unplaced.
+     */
+    removeFromTree(documentId: string): Promise<void>;
+    /**
+     * Read a node's subtree as a nested {@link TreeNode} forest, hydrated to
+     * `ClientDocument`s. `rootDocumentId: null` (default) returns the whole tree
+     * from the collection roots; a value returns the subtree rooted at (and
+     * including) that node. Children are ordered per-parent. `status` defaults to
+     * `'published'` (the client default) — an unpublished node hides its whole
+     * subtree in that mode.
+     */
+    getSubtree<F = Record<string, any>>(options?: GetSubtreeOptions<F>): Promise<TreeNode<F>[]>;
+    /**
+     * Walk a document's ancestor chain upward, returning the ancestors
+     * **root-first** (the breadcrumb trail, excluding the node itself), hydrated
+     * to `ClientDocument`s. In `'published'` mode (the client default) the walk
+     * applies status-at-edge: it stops at the first unpublished ancestor (a
+     * truncated chain), so a broken spine surfaces as a short chain the caller can
+     * detect rather than a silently-compacted one.
+     */
+    getAncestors<F = Record<string, any>>(documentId: string, options?: GetAncestorsOptions<F>): Promise<ClientDocument<F>[]>;
+    /**
+     * Resolve a document's placement state in the tree — the tri-state that
+     * `getAncestors` cannot express (it returns `[]` for both a root and an
+     * unplaced node). Returns `{ placed, parentDocumentId }`: `placed: false` is
+     * *unplaced* (no edge row), `placed: true` with a null parent is a *root*, and
+     * a non-null parent is a *child*. Structure-only — no document hydration.
+     */
+    getTreeParent(documentId: string): Promise<{
+        placed: boolean;
+        parentDocumentId: string | null;
+    }>;
     /**
      * Build a fresh `DocumentLifecycleContext` for a write call. Pulls the
      * resolved collection id, inherits the client-wide logger and storage
@@ -166,6 +212,23 @@ export declare class CollectionHandle {
      * other per-request state into the adapter without re-resolving.
      */
     private resolveAndAssertRead;
+    /**
+     * Guard that this collection opts into the document-tree primitive. The
+     * tree commands are inert (and the read path meaningless) for a non-tree
+     * collection, so fail loudly rather than silently writing edge rows that
+     * nothing will read.
+     */
+    private assertTreeCollection;
+    /**
+     * Batch-hydrate a set of tree node document ids into shaped
+     * `ClientDocument`s, keyed by document id. Reuses the populate batch read
+     * (`getDocumentsByDocumentIds`) under the requested `readMode` — the tree's
+     * own status-at-edge filtering already happened structurally, so a node
+     * absent here in `'published'` mode simply has no published version. Fires
+     * `afterRead` per node (deduped within one shared `ReadContext`) to stay
+     * consistent with the other client read paths.
+     */
+    private hydrateTreeNodes;
     /**
      * Invoke `populateDocuments` on a freshly-read (raw, storage-shape) set
      * of documents when the caller asked for populate. No-op otherwise.

package/dist/collection-handle.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { applyAfterRead, applyBeforeRead, assertActorCanPerform, changeDocumentStatus, createDocument, createReadContext, deleteDocument, mergePredicates, parseSort, parseWhere, populateDocuments, populateRichTextFields, restoreDocumentVersion, unpublishDocument, updateDocument, } from '@byline/core';
+import { applyAfterRead, applyBeforeRead, assertActorCanPerform, changeDocumentStatus, createDocument, createReadContext, deleteDocument, ERR_VALIDATION, mergePredicates, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, restoreDocumentVersion, unpublishDocument, updateDocument, } from '@byline/core';
 import { shapeDocument, shapePopulatedInPlace } from './response.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
@@ -424,6 +424,122 @@ export class CollectionHandle {
         return this.shapeWithPopulated(raw);
     }
     // -------------------------------------------------------------------------
+    // Document tree (the `tree: true` primitive — docs/DOCUMENT-TREE.md)
+    //
+    // A document-grain, unversioned single-parent ordered hierarchy. Reads/writes
+    // here go through the storage adapter's dedicated tree commands, NOT the
+    // store_relation / populate pipeline. Every method requires the collection to
+    // be a tree (`tree: true`); writes assert the `update` ability (structural
+    // moves are metadata-level updates), reads assert `read`.
+    // -------------------------------------------------------------------------
+    /**
+     * Place or move a document within this collection's tree — a single upsert
+     * covering place, reorder, and re-parent (they differ only in whether the
+     * parent changes). Document-grain and unversioned: mints no new document
+     * version and does not touch workflow status. The storage layer enforces the
+     * cycle and same-collection invariants atomically. Returns the minted
+     * per-parent `order_key`.
+     */
+    async placeTreeNode(documentId, options) {
+        this.assertTreeCollection();
+        const ctx = await this.buildLifecycleContext();
+        return placeTreeNodeLifecycle(ctx, {
+            documentId,
+            parentDocumentId: options.parentDocumentId,
+            beforeDocumentId: options.beforeDocumentId ?? null,
+            afterDocumentId: options.afterDocumentId ?? null,
+        });
+    }
+    /**
+     * Remove a document from the tree, returning it to the *unplaced* state (still
+     * in the collection, but not in any table of contents). Distinct from
+     * deleting the document. No-op when already unplaced.
+     */
+    async removeFromTree(documentId) {
+        this.assertTreeCollection();
+        const ctx = await this.buildLifecycleContext();
+        await removeFromTreeLifecycle(ctx, { documentId });
+    }
+    /**
+     * Read a node's subtree as a nested {@link TreeNode} forest, hydrated to
+     * `ClientDocument`s. `rootDocumentId: null` (default) returns the whole tree
+     * from the collection roots; a value returns the subtree rooted at (and
+     * including) that node. Children are ordered per-parent. `status` defaults to
+     * `'published'` (the client default) — an unpublished node hides its whole
+     * subtree in that mode.
+     */
+    async getSubtree(options = {}) {
+        this.assertTreeCollection();
+        await this.resolveAndAssertRead();
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
+        const locale = options.locale ?? this.client.defaultLocale;
+        const readMode = resolveReadMode(options.status);
+        const structure = await this.client.db.queries.documents.getTreeSubtree({
+            collectionId,
+            rootDocumentId: options.rootDocumentId ?? null,
+            maxDepth: options.depth,
+            readMode,
+        });
+        if (structure.length === 0)
+            return [];
+        const shapedById = await this.hydrateTreeNodes(collectionId, structure.map((n) => n.document_id), locale, readMode, options.select);
+        // Assemble the nested forest. Rows arrive pre-order, so a parent is always
+        // materialised before its children; a row whose parent is not in the result
+        // set (null parent, or the requested root's own parent) is a top-level node.
+        const nodeById = new Map();
+        const roots = [];
+        for (const row of structure) {
+            const document = shapedById.get(row.document_id);
+            if (document == null)
+                continue;
+            const node = { document, depth: row.depth, children: [] };
+            nodeById.set(row.document_id, node);
+            const parent = row.parent_document_id != null ? nodeById.get(row.parent_document_id) : undefined;
+            if (parent)
+                parent.children.push(node);
+            else
+                roots.push(node);
+        }
+        return roots;
+    }
+    /**
+     * Walk a document's ancestor chain upward, returning the ancestors
+     * **root-first** (the breadcrumb trail, excluding the node itself), hydrated
+     * to `ClientDocument`s. In `'published'` mode (the client default) the walk
+     * applies status-at-edge: it stops at the first unpublished ancestor (a
+     * truncated chain), so a broken spine surfaces as a short chain the caller can
+     * detect rather than a silently-compacted one.
+     */
+    async getAncestors(documentId, options = {}) {
+        this.assertTreeCollection();
+        await this.resolveAndAssertRead();
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
+        const locale = options.locale ?? this.client.defaultLocale;
+        const readMode = resolveReadMode(options.status);
+        const ancestors = await this.client.db.queries.documents.getTreeAncestors({
+            document_id: documentId,
+            readMode,
+        });
+        if (ancestors.length === 0)
+            return [];
+        const ids = ancestors.map((a) => a.document_id);
+        const shapedById = await this.hydrateTreeNodes(collectionId, ids, locale, readMode, options.select);
+        // Preserve root-first order; drop ancestors not visible in this read mode.
+        return ids.map((id) => shapedById.get(id)).filter((d) => d != null);
+    }
+    /**
+     * Resolve a document's placement state in the tree — the tri-state that
+     * `getAncestors` cannot express (it returns `[]` for both a root and an
+     * unplaced node). Returns `{ placed, parentDocumentId }`: `placed: false` is
+     * *unplaced* (no edge row), `placed: true` with a null parent is a *root*, and
+     * a non-null parent is a *child*. Structure-only — no document hydration.
+     */
+    async getTreeParent(documentId) {
+        this.assertTreeCollection();
+        await this.resolveAndAssertRead();
+        return this.client.db.queries.documents.getTreeParent({ document_id: documentId });
+    }
+    // -------------------------------------------------------------------------
     // Internals
     // -------------------------------------------------------------------------
     /**
@@ -459,6 +575,48 @@ export class CollectionHandle {
         assertActorCanPerform(requestContext, this.definition.path, 'read');
         return requestContext;
     }
+    /**
+     * Guard that this collection opts into the document-tree primitive. The
+     * tree commands are inert (and the read path meaningless) for a non-tree
+     * collection, so fail loudly rather than silently writing edge rows that
+     * nothing will read.
+     */
+    assertTreeCollection() {
+        if (this.definition.tree !== true) {
+            throw ERR_VALIDATION({
+                message: `collection '${this.definition.path}' is not a document tree; set \`tree: true\` on its collection definition to use the tree API`,
+                details: { collectionPath: this.definition.path },
+            });
+        }
+    }
+    /**
+     * Batch-hydrate a set of tree node document ids into shaped
+     * `ClientDocument`s, keyed by document id. Reuses the populate batch read
+     * (`getDocumentsByDocumentIds`) under the requested `readMode` — the tree's
+     * own status-at-edge filtering already happened structurally, so a node
+     * absent here in `'published'` mode simply has no published version. Fires
+     * `afterRead` per node (deduped within one shared `ReadContext`) to stay
+     * consistent with the other client read paths.
+     */
+    async hydrateTreeNodes(collectionId, documentIds, locale, readMode, select) {
+        const shapedById = new Map();
+        if (documentIds.length === 0)
+            return shapedById;
+        const rawDocs = await this.client.db.queries.documents.getDocumentsByDocumentIds({
+            collection_id: collectionId,
+            document_ids: documentIds,
+            locale,
+            readMode,
+            fields: select,
+        });
+        const readContext = createReadContext();
+        for (const raw of rawDocs) {
+            const doc = raw;
+            await applyAfterRead({ doc, definition: this.definition, readContext });
+            shapedById.set(doc.document_id, this.shapeWithPopulated(doc));
+        }
+        return shapedById;
+    }
     /**
      * Invoke `populateDocuments` on a freshly-read (raw, storage-shape) set
      * of documents when the caller asked for populate. No-op otherwise.

package/dist/index.d.ts

@@ -8,4 +8,4 @@
 export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, } from '@byline/core';
 export { BylineClient, createBylineClient } from './client.js';
 export { CollectionHandle } from './collection-handle.js';
-export type { AuditLogOptions, BylineClientConfig, ClientDocument, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, PopulatedRelation, SortDirection, SortSpec, UpdateOptions, WhereClause, WhereValue, WithPopulated, } from './types.js';
+export type { AuditLogOptions, BylineClientConfig, ClientDocument, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, PlaceTreeNodeOptions, PopulatedRelation, SortDirection, SortSpec, TreeNode, UpdateOptions, WhereClause, WhereValue, WithPopulated, } from './types.js';

package/dist/types.d.ts

@@ -293,6 +293,63 @@ export interface UpdateOptions {
      */
     availableLocales?: string[];
 }
+/**
+ * Options for `CollectionHandle.placeTreeNode(documentId, options)`. Places or
+ * moves a node within the collection's single-parent ordered tree — one upsert
+ * covering place / reorder / re-parent.
+ *
+ * Neighbour semantics match `reorderCollectionDocument`: `beforeDocumentId` is
+ * the sibling the node should land immediately **after** (its left neighbour);
+ * `afterDocumentId` is the sibling it should land immediately **before** (its
+ * right neighbour). Both are resolved within the *target* parent group; either
+ * may be null/omitted (append as last child, or prepend before a given sibling).
+ */
+export interface PlaceTreeNodeOptions {
+    /** The new parent; `null` makes the node a root. */
+    parentDocumentId: string | null;
+    /** Left neighbour — the node lands immediately after it. */
+    beforeDocumentId?: string | null;
+    /** Right neighbour — the node lands immediately before it. */
+    afterDocumentId?: string | null;
+}
+/**
+ * Options for `CollectionHandle.getSubtree(options)`. Reads a node's subtree as
+ * a nested {@link TreeNode} forest. `rootDocumentId: null` (the default) reads
+ * the whole tree from the collection's roots; a value reads the subtree rooted
+ * at (and including) that node. `depth` bounds the descent (0-based; the root is
+ * depth 0). `status` follows the usual published/any selector — in `'published'`
+ * mode an unpublished node hides its entire subtree (the spine breaks).
+ */
+export interface GetSubtreeOptions<F = Record<string, any>> extends StatusControls {
+    rootDocumentId?: string | null;
+    depth?: number;
+    /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
+    locale?: string;
+    /** Return only these fields on each node. Omit for all fields. */
+    select?: (keyof F & string)[] | string[];
+}
+/**
+ * Options for `CollectionHandle.getAncestors(documentId, options)`. Walks the
+ * node's ancestor chain upward, returning the ancestors **root-first** (the
+ * breadcrumb trail, excluding the node itself). In `'published'` mode only
+ * ancestors with a published version are returned.
+ */
+export interface GetAncestorsOptions<F = Record<string, any>> extends StatusControls {
+    /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
+    locale?: string;
+    /** Return only these fields on each ancestor. Omit for all fields. */
+    select?: (keyof F & string)[] | string[];
+}
+/**
+ * A node in a hydrated document tree. `document` is the fully-shaped
+ * `ClientDocument`; `depth` is 0-based from the subtree root; `children` are the
+ * node's ordered children (per-parent `order_key` order).
+ */
+export interface TreeNode<F = Record<string, any>> {
+    document: ClientDocument<F>;
+    depth: number;
+    children: TreeNode<F>[];
+}
 /**
  * A where clause maps field names (or reserved document-level names like
  * `status` and `path`) to either a bare value (equality), an operator

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.12.2",
+  "version": "3.13.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -38,8 +38,8 @@
   ],
   "dependencies": {
     "npm-run-all": "^4.1.5",
-    "@byline/auth": "3.12.2",
-    "@byline/core": "3.12.2"
+    "@byline/auth": "3.13.0",
+    "@byline/core": "3.13.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
@@ -51,7 +51,7 @@
     "tsx": "^4.22.3",
     "typescript": "6.0.3",
     "vitest": "^4.1.7",
-    "@byline/db-postgres": "3.12.2"
+    "@byline/db-postgres": "3.13.0"
   },
   "publishConfig": {
     "access": "public",