@byline/client 0.9.3

package/dist/collection-handle.d.ts

@@ -0,0 +1,182 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
+import type { BylineClient } from './client.js';
+import type { ClientDocument, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, HistoryOptions, UpdateOptions } from './types.js';
+/**
+ * A handle scoped to a single collection. Provides read (and eventually write)
+ * operations against that collection's documents.
+ *
+ * Created via `client.collection('posts')`.
+ */
+export declare class CollectionHandle {
+    private client;
+    private definition;
+    constructor(client: BylineClient, definition: CollectionDefinition);
+    /**
+     * Find documents with optional filtering, sorting, pagination, and field
+     * selection.
+     *
+     * All queries are routed through `findDocuments()` which supports
+     * document-level conditions (status, text search), field-level filters
+     * (EXISTS subqueries against EAV store tables), and field-level sorting
+     * (LATERAL JOINs).
+     */
+    find<F = Record<string, any>>(options?: FindOptions<F>): Promise<FindResult<F>>;
+    /**
+     * Find a single document matching the given options. Returns `null` if no
+     * document matches.
+     */
+    findOne<F = Record<string, any>>(options?: FindOneOptions<F>): Promise<ClientDocument<F> | null>;
+    /**
+     * Find a document by its logical document ID.
+     */
+    findById<F = Record<string, any>>(documentId: string, options?: FindByIdOptions<F>): Promise<ClientDocument<F> | null>;
+    /**
+     * Find a document by its URL path/slug. Returns `null` when no document
+     * exists at the given path (the storage adapter resolves missing paths
+     * to `null` rather than throwing).
+     */
+    findByPath<F = Record<string, any>>(path: string, options?: FindByPathOptions<F>): Promise<ClientDocument<F> | null>;
+    /**
+     * Create a new document in this collection.
+     *
+     * `data` is a plain object matching the collection's field shape. When
+     * `options.status` is omitted the collection's default status (from its
+     * workflow definition) is used.
+     */
+    create(data: Record<string, any>, options?: CreateOptions): Promise<CreateDocumentResult>;
+    /**
+     * Update an existing document via full replacement (PUT semantics).
+     * Creates a new immutable version row. Hooks receive the real previous
+     * version as `originalData`.
+     */
+    update(documentId: string, data: Record<string, any>, options?: UpdateOptions): Promise<UpdateDocumentResult>;
+    /**
+     * Change a document's workflow status. The transition is validated
+     * against the collection's declared workflow (±1 step or reset-to-first);
+     * transitioning to `'published'` auto-archives any other published
+     * versions of the same document.
+     */
+    changeStatus(documentId: string, nextStatus: string): Promise<ChangeStatusResult>;
+    /**
+     * Archive the currently-published version(s) of a document.
+     */
+    unpublish(documentId: string): Promise<UnpublishResult>;
+    /**
+     * Soft-delete a document. All versions are flagged `is_deleted = true`
+     * and disappear from read paths (the `current_documents` view filters
+     * them out). When the collection has any upload-capable image/file
+     * field and a storage provider is configured, the original file and
+     * every persisted variant on each upload-capable field are removed
+     * after the DB soft-delete — failures there are logged but non-fatal.
+     */
+    delete(documentId: string): Promise<DeleteDocumentResult>;
+    /**
+     * Count documents visible to the current actor, optionally filtered by
+     * status.
+     *
+     * Applies the collection's `beforeRead` predicate so the count reflects
+     * only the rows the actor can see (multi-tenant scoping, owner-only
+     * drafts, soft-delete hide, etc).
+     */
+    count(where?: {
+        status?: string;
+        _bypassBeforeRead?: true;
+    }): Promise<number>;
+    /**
+     * Per-status document counts for this collection. Used by admin status
+     * bars / dashboards. Applies `beforeRead` so per-status counts reflect
+     * only the actor's visible rows.
+     */
+    countByStatus(options?: {
+        _bypassBeforeRead?: true;
+    }): Promise<Array<{
+        status: string;
+        count: number;
+    }>>;
+    /**
+     * Fetch the version history for a single document. Applies `beforeRead`
+     * as an access gate via `findById` — if the actor can't see the
+     * document at all, history returns an empty result rather than
+     * leaking version metadata.
+     *
+     * Each version in the response is a shaped `ClientDocument`. Pagination
+     * mirrors the storage adapter's `{ documents, meta }` shape, then is
+     * mapped to the same `{ docs, meta }` envelope `find()` returns.
+     */
+    history<F = Record<string, any>>(documentId: string, options?: HistoryOptions): Promise<FindResult<F>>;
+    /**
+     * Fetch a specific version of a document by its `documentVersionId`.
+     * Used by admin diff views.
+     *
+     * Pass-through to `getDocumentByVersion`; access enforcement falls back
+     * to the collection-level `read` ability (asserted at the top of every
+     * read entry point). Row-level `beforeRead` does **not** apply here —
+     * version-by-id is a history-viewing primitive and the caller is
+     * expected to have already passed an access check on the parent
+     * document. Use `history()` instead if you want the access gate.
+     */
+    findByVersion<F = Record<string, any>>(versionId: string, options?: FindByVersionOptions<F>): Promise<ClientDocument<F> | null>;
+    /**
+     * Build a fresh `DocumentLifecycleContext` for a write call. Pulls the
+     * resolved collection id, inherits the client-wide logger and storage
+     * provider, and includes the collection definition so hooks can observe it.
+     */
+    private buildLifecycleContext;
+    /**
+     * Resolve the caller's `RequestContext` and enforce the read ability
+     * for this collection. Called at the top of every read entry point so
+     * reads and writes both fail closed at the service boundary.
+     *
+     * Returns the resolved context so callers can thread `readMode` and
+     * other per-request state into the adapter without re-resolving.
+     */
+    private resolveAndAssertRead;
+    /**
+     * Invoke `populateDocuments` on a freshly-read (raw, storage-shape) set
+     * of documents when the caller asked for populate. No-op otherwise.
+     *
+     * Runs BEFORE `shapeDocument` so the populate service sees the raw
+     * `{document_id, fields}` shape it expects. The shape pass
+     * (`shapeWithPopulated`) then walks the mutated tree and converts every
+     * newly-inserted raw sub-document into a `ClientDocument`.
+     */
+    private populateIfRequested;
+    /**
+     * Apply richtext populate to a freshly-read set of source documents.
+     * Mirrors what `populateDocuments` does for materialised targets, but
+     * runs unconditionally for sources because `richTextPopulate` is a
+     * framework-managed phase rather than a user-opted DSL like
+     * `populate`/`depth`. Each leaf is gated by its own
+     * `populateRelationsOnRead` inside the service. No-ops when no adapter
+     * is registered.
+     */
+    private richTextPopulateSources;
+    /**
+     * Resolve and cache the `beforeRead` hook predicate for this collection
+     * inside the current `ReadContext`. Honours `_bypassBeforeRead` (admin
+     * tooling, seeds, migrations).
+     */
+    private resolveBeforeReadPredicate;
+    /**
+     * Like `resolveBeforeReadPredicate`, but parses the predicate to the
+     * adapter-facing `DocumentFilter[]` shape used by `getDocumentById` /
+     * `getDocumentByPath`. Returns `undefined` (not `[]`) when there is no
+     * scoping, so the adapter can skip the loop entirely.
+     */
+    private resolveBeforeReadFilters;
+    /**
+     * Shape a raw doc to `ClientDocument<F>`, then recursively shape any
+     * populated raw sub-documents inside its `fields`. Stubs
+     * (`_resolved: false` / `_cycle: true`) and plain field values are
+     * preserved by reference.
+     */
+    private shapeWithPopulated;
+}
+//# sourceMappingURL=collection-handle.d.ts.map

package/dist/collection-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-handle.d.ts","sourceRoot":"","sources":["../src/collection-handle.ts"],"names":[],"mappings":"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"}