canopycms 0.0.62 → 0.0.64

package/dist/content-store.d.ts

@@ -1,6 +1,6 @@
-import type { FlatSchemaItem, EntryTypeConfig } from './config';
-import { ContentIdIndex } from './content-id-index';
-import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths';
+import type { EntrySchema, FlatSchemaItem, EntryTypeConfig } from './config/index.js';
+import { ContentIdIndex } from './content-id-index.js';
+import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths/index.js';
 export type MarkdownDocument = {
     format: 'md' | 'mdx';
     data: Record<string, unknown>;
@@ -92,6 +92,25 @@ export declare class DuplicateContentIdError extends ContentConflictError {
     readonly paths: readonly string[];
     constructor(contentId: string, paths: readonly string[]);
 }
+/**
+ * Thrown when a create or rename would give a SECOND entry a `urlPath` another entry already
+ * holds -- the write-boundary half of the invariant `assertNoDuplicateUrlPaths` enforces at build
+ * time (see url-collision.ts for which shapes count and, just as importantly, which do not).
+ *
+ * Why refuse rather than write: only one of the two entries can be served at that URL, so the
+ * other silently has no route anywhere. Allowing the write trades a clear error now for a page
+ * that quietly does not exist later -- and, because the loser is picked by resolver precedence
+ * rather than by the author, not necessarily the page they were editing.
+ *
+ * A `ContentConflictError` subclass so every existing 409 mapping keeps working; the distinct
+ * type exists so the API can surface THIS message rather than the generic "modified by another
+ * editor", which would send the editor into a reload-and-retry loop that cannot succeed.
+ */
+export declare class UrlPathConflictError extends ContentConflictError {
+    /** Absolute path of the entry already holding the contested URL. */
+    readonly conflictingPath: string;
+    constructor(message: string, conflictingPath: string);
+}
 /**
  * Get the default entry type from a collection's entries array.
  * Returns the entry marked as default, or the first one, or undefined if no entries.
@@ -122,6 +141,46 @@ export interface ContentStoreOptions {
      */
     contentWriteLockWaitMs?: number;
 }
+/**
+ * Per-batch memo for reference resolution, keyed by content ID.
+ *
+ * Exists because a batch surface resolves the SAME reference over and over: a shared
+ * block ("call to action", "promo card") referenced by 40 pages costs 40 separate
+ * `read()`s of one small file in a single `listEntries()` pass, and a search-index build
+ * over thousands of entries multiplies that. Pass one cache through a whole batch and
+ * each distinct target is read once.
+ *
+ * Values are the in-flight **promise**, not the settled value, so concurrent lookups
+ * inside a `Promise.all` collapse onto one read rather than each starting their own —
+ * the same in-flight dedup `ContentStore.indexBuild` uses for index rebuilds.
+ *
+ * What is cached is the READ, not the object handed out: every occurrence receives its own
+ * deep copy, so a caller mutating one resolved reference cannot rewrite it for the other 39
+ * entries pointing at the same target. See `resolveSingleReference` for why that matters and
+ * why it does not undo the saving.
+ *
+ * ## Lifetime and invalidation
+ *
+ * There is no invalidation, and that is the design: a cache lives inside a single
+ * `listEntries()` / `buildContentTree()` call and is dropped when it returns. That is
+ * strictly shorter than the lifetime of the `ContentStore` whose memoized `idIndex()` it
+ * sits on top of, so it introduces no staleness window that store did not already have,
+ * and it is out of scope for the generation-marker protocol in
+ * `docs/concurrency.md` (which governs caches rebuilt by scanning that OUTLIVE the
+ * mutations they can miss). Never make one module-global, never persist one, and never
+ * reuse one across requests.
+ *
+ * Misses are memoized alongside hits, deliberately: one batch should be internally
+ * coherent, and a shared block resolving to data on page 1 and to `null` on page 40 of
+ * the same sitemap is worse than either consistent answer. The accepted cost is that a
+ * later occurrence in the same batch can no longer get incidentally lucky after a
+ * sibling lookup wins the stale-index refresh throttle. Each DISTINCT id still gets its
+ * full self-healing retry, because that retry happens inside the memoized promise (see
+ * `resolveSingleReference`).
+ */
+export type ReferenceResolveCache = Map<string, Promise<Record<string, unknown> | null>>;
+/** Create a cache for one batch of reference resolution. See {@link ReferenceResolveCache}. */
+export declare const createReferenceResolveCache: () => ReferenceResolveCache;
 export declare class ContentStore {
     private readonly root;
     /** See ContentStoreOptions.contentRootName — the ID index scan root. */
@@ -274,6 +333,15 @@ export declare class ContentStore {
      * existing entries lock on a per-slug create-key (createLockKey()).
      */
     private entryLockKey;
+    /**
+     * Refuse a create/rename that would give a second entry a `urlPath` another entry already
+     * holds. See url-collision.ts for the two shapes that count, and the legitimate
+     * landing-page-beside-a-collection shape that deliberately does not.
+     *
+     * @param collectionDir Absolute physical directory the entry will live in.
+     * @param slug The entry's slug, as it will be written.
+     */
+    private assertUrlPathAvailable;
     /**
      * Build absolute and relative paths with security validation.
      * All entries use the unified filename pattern: {type}.{slug}.{id}.{ext}
@@ -302,7 +370,16 @@ export declare class ContentStore {
         absolutePath: string;
         relativePath: PhysicalPath;
         id?: string;
-        entryTypeName?: string;
+        /**
+         * Always populated for a valid schema item: the collection branch below
+         * always resolves a name (falling back to `'entry'` when the collection
+         * has no matching/default entry type config), and the entry-type branch
+         * delegates to it with its own name set explicitly. Only non-collection,
+         * non-entry-type schema items (impossible via the public API, which only
+         * ever resolves to one of those two) skip both branches, hitting the
+         * throw below instead of returning at all.
+         */
+        entryTypeName: string;
         /**
          * True if this slug already had a file on disk (a directory-scan finding,
          * or `options.existingId` asserting one) -- i.e. this resolution is an
@@ -417,13 +494,72 @@ export declare class ContentStore {
         collection: LogicalPath;
         slug: Slug;
     }>>;
+    /**
+     * Resolve every `reference` field in `data` against `fields`, returning a copy.
+     *
+     * This is what `read()` applies automatically (unless `resolveReferences: false`), exposed
+     * so BATCH surfaces can opt into the same resolution without duplicating the walk: the
+     * listing primitives in content-listing.ts and content-tree.ts read entry files straight
+     * off disk and never touch this store, so before this existed a `reference` field reached
+     * `listEntries()`/`buildContentTree()` callers as a bare id string or `null`.
+     *
+     * Pass one {@link ReferenceResolveCache} across a whole batch so a target referenced by
+     * many entries is read once rather than once per referencing entry. Omit `cache` and the
+     * behavior is exactly what `read()` has always done, unmemoized.
+     *
+     * **Path ACLs are not consulted for the targets.** Resolution goes through this store's
+     * own `read()`, below the per-entry permission check in content-reader.ts — so a resolved
+     * target may be an entry the caller could not `read()` directly. That is pre-existing
+     * `read()` behavior, matched here on purpose so one rule covers both; see the
+     * `resolveReferences` option in content-listing.ts for the note adopters see.
+     */
+    resolveReferences(data: Record<string, unknown>, fields: EntrySchema, cache?: ReferenceResolveCache): Promise<Record<string, unknown>>;
     /**
      * Recursively resolve reference fields in data.
      * This traverses objects, arrays, and blocks to find and resolve all reference fields.
      */
     private resolveReferencesInData;
     /**
-     * Resolve a single reference ID to full entry data.
+     * Resolve a single reference ID to full entry data, memoized when a batch cache is
+     * supplied. Without a cache this is a straight pass-through to the uncached path, so
+     * `read()` behaves exactly as it always has.
+     *
+     * Every occurrence gets its OWN deep copy, even on a cache hit. Without that, the memo
+     * would hand one shared object to all 40 entries referencing the same block — a mutation
+     * in one caller's `extract` (truncating a body for a search index, deleting a field) would
+     * silently rewrite it for every sibling, and both `list: true` elements of `[id, id]` would
+     * be the same instance. The copy is what keeps the cache a pure performance optimization
+     * instead of a semantic change.
+     *
+     * Note the uncached path is NOT the clean baseline it looks like. For a json/yaml target it
+     * genuinely reparses fresh per occurrence, but for md/mdx gray-matter serves `data` from a
+     * process-global content-keyed cache, so `resolveSingleReferenceOnce`'s top-level spread
+     * severs exactly one level and NESTED frontmatter objects alias across occurrences, calls and
+     * requests. That is pre-existing `read()` behavior and out of scope here — deliberately, since
+     * touching it would change `read()` — but it means the cached path is the safer of the two,
+     * not a relaxation of a guarantee the uncached one provides. See
+     * `.claude/future-tasks/graymatter-cache-shared-frontmatter.md`.
+     *
+     * What the copy costs, measured rather than assumed (2000 occurrences of one target, local
+     * disk, so every read hits the page cache — the friendliest possible case for NOT caching):
+     * a snippet-sized target is ~63x cheaper to clone than to re-read-and-parse, while a 265KB
+     * JSON target is ~0.8x, i.e. cloning is marginally SLOWER than reparsing it. So the win is
+     * large in the case this exists for and roughly a wash at the pathological end, never a
+     * blow-up. Two things keep the bad end narrow: an md/mdx target resolves to its FRONTMATTER
+     * only *unless the field sets `includeBody`* (`read()` puts the body on `doc.body`, which
+     * `resolveSingleReferenceOnce` spreads in only for an embedding field), so by default body
+     * size is irrelevant no matter how long the document and only a genuinely huge JSON/YAML
+     * target reaches the wash. **`includeBody: true` is the case that CAN reach it on markdown**:
+     * the body then sits inside the memoized object and is cloned once per referencing entry, so
+     * a long document embedded by many pages pays that repeatedly — the reason `includeBody`
+     * exists as an opt-in per field rather than as resolution's default. And in the deployment this
+     * targets, content lives on EFS/NFS where the syscall the memo removes dominates parse and
+     * clone alike, which the local-disk numbers above understate badly. Correctness is the
+     * reason for the copy regardless; the numbers are here so nobody has to re-derive them
+     * before touching this.
+     */
+    private resolveSingleReference;
+    /**
      * Returns null if the reference is invalid or missing.
      * Includes id, slug, and collection fields for debugging.
      *
@@ -437,8 +573,12 @@ export declare class ContentStore {
      * idIndex() dedupes concurrent builds — so a sibling call that wins the
      * throttle and rebuilds heals every other miss in the same batch, not just
      * the first.
+     *
+     * A {@link ReferenceResolveCache} sits ABOVE this, never inside it, so every
+     * distinct id still runs the full refresh-and-retry above. What a cache changes
+     * is only that repeats of the SAME id in one batch share that one attempt's
+     * outcome instead of each getting an independent throw of the dice.
      */
-    private resolveSingleReference;
+    private resolveSingleReferenceUncached;
     private resolveSingleReferenceOnce;
 }
-//# sourceMappingURL=content-store.d.ts.map