canopycms 0.0.67-int.90 → 0.0.67

package/dist/entry-schema-registry.js

@@ -26,70 +26,34 @@ function findFieldType(fields, dottedPath) {
 /**
  * Create a type-safe entry schema registry with runtime validation.
  *
- * The KEYS in the registry are the strings that `.collection.json` files (and
- * the editor wire format) use to look up each schema via the `entry.schema`
- * property. You can pick any string — but the **recommended convention is to
- * key by the entry-type name** (the filename token, the same string that
- * appears in `meta.entryType` in `buildContentTree` callbacks). When you do
- * that, `EntryTypesFromRegistry<typeof yourRegistry>` derives the
- * discriminated-union map for `buildContentTree`'s `TEntryTypes` parameter
- * automatically — no parallel interface to maintain.
+ * The KEYS are the strings `.collection.json` files (and the editor wire format)
+ * use to look up each schema via the `entry.schema` property. Any string works,
+ * but **key by the entry-type name** — the filename token, the same string
+ * `meta.entryType` carries in `buildContentTree` callbacks — because then
+ * `EntryTypesFromRegistry<typeof yourRegistry>` derives the discriminated-union
+ * map for `buildContentTree`'s `TEntryTypes` parameter with no parallel
+ * interface to maintain. Keyed any other way, the derived map is keyed by that
+ * string instead and will not plug into `TEntryTypes`.
+ *
+ * Rejected at call time: an empty registry; a schema that is not a non-empty
+ * `EntrySchema` array; more than one `isTitle` per schema, or one on a non-string
+ * field or inside a list; more than one `isBody`, or one on a field that is not
+ * markdown/mdx or is named one of `RESOLVED_REFERENCE_KEYS`. This is also the one
+ * place the shared field-shape checks run: select fields must have options,
+ * reference fields must have `collections` or `entryTypes`, no inline groups
+ * inside object/block fields, no field-name collisions after group flattening.
  *
  * @example
- * Recommended — keys are entry-type names:
  * ```typescript
- * import { createEntrySchemaRegistry } from 'canopycms/server'
- * import { type EntryTypesFromRegistry, defineEntrySchema } from 'canopycms'
- *
- * export const partnerSchema = defineEntrySchema([
- *   { name: 'name', type: 'string', label: 'Name', isTitle: true },
- *   { name: 'isFictional', type: 'boolean', label: 'Fictional?' },
- * ])
- * export const docSchema = defineEntrySchema([
- *   { name: 'title', type: 'string', label: 'Title' },
- * ])
- *
  * export const entrySchemaRegistry = createEntrySchemaRegistry({
- *   partner: partnerSchema,
+ *   partner: partnerSchema, // .collection.json: { "name": "partner", "schema": "partner" }
  *   doc: docSchema,
  * })
- *
- * // Then in .collection.json:
- * //   { "name": "partner", "format": "yaml", "schema": "partner" }
- *
- * // Derive entry-type map for typed narrowing:
  * export type EntryTypes = EntryTypesFromRegistry<typeof entrySchemaRegistry>
- *
- * // Per-schema aliases stay one line each, anchored to the registry:
  * export type PartnerContent = EntryTypes['partner']
  * ```
- *
- * @example
- * Also valid — keys are schema-variable names (prior convention):
- * ```typescript
- * export const entrySchemaRegistry = createEntrySchemaRegistry({
- *   partnerSchema,  // JS shorthand — key is the string "partnerSchema"
- *   docSchema,
- * })
- *
- * // .collection.json must then say:
- * //   { "name": "partner", "schema": "partnerSchema" }
- * //
- * // EntryTypesFromRegistry produces a map keyed by "partnerSchema" rather than
- * // by "partner", so it can't plug straight into buildContentTree's TEntryTypes.
- * // Either rekey the registry to the recommended convention, or declare the
- * // entry-type map manually using TypeFromEntrySchema<typeof partnerSchema>.
- * ```
- *
- * Runtime validation: registry must be non-empty, each schema must be a
- * non-empty `EntrySchema` array, at most one `isTitle` per schema (string
- * fields only), at most one `isBody` per schema (markdown/mdx only). Field-
- * shape checks: select fields must have options, reference fields must have
- * `collections` or `entryTypes`, no inline groups inside object/block fields,
- * no field-name collisions after group flattening.
  */
 export function createEntrySchemaRegistry(registry) {
-    // Validate that registry is not empty
     if (!registry || typeof registry !== 'object') {
         throw new Error('Entry schema registry must be an object');
     }
@@ -97,7 +61,6 @@ export function createEntrySchemaRegistry(registry) {
     if (keys.length === 0) {
         throw new Error('Entry schema registry cannot be empty');
     }
-    // Validate each entry schema
     for (const [key, schema] of Object.entries(registry)) {
         if (!Array.isArray(schema)) {
             throw new Error(`Entry schema registry entry "${key}" must be an array of FieldConfig`);
@@ -129,9 +92,6 @@ export function createEntrySchemaRegistry(registry) {
         if (reservedBodyField) {
             throw new Error(`Entry schema registry entry "${key}": field "${reservedBodyField}" has isBody: true but "${reservedBodyField}" is reserved — reference resolution sets ${RESOLVED_REFERENCE_KEYS.map((k) => `"${k}"`).join(', ')} on a resolved reference, and a body field with one of those names would overwrite it. Rename the field (the body's field name is yours to choose; only these four are reserved).`);
         }
-        // Field-shape checks moved here from validateCanopyConfig — these used to walk
-        // the (now-removed) inline-config schema; the registry is now the canonical
-        // entry point for entry schemas, so they run here.
         ensureSelectFieldsHaveOptions(schema);
         ensureReferenceFieldsHaveScope(schema);
         ensureNoGroupsInsideComplexFields(schema);
@@ -140,14 +100,9 @@ export function createEntrySchemaRegistry(registry) {
     return registry;
 }
 /**
- * Validates that entry schema references in .collection.json files exist in the registry.
- *
- * Useful for build-time validation to catch schema reference errors early
- * rather than at runtime on first request.
- *
- * @param entrySchemaRegistry - The entry schema registry mapping names to field definitions
- * @param contentPath - Path to the content directory containing .collection.json files
- * @returns Promise that resolves if validation passes, rejects with descriptive error if not
+ * Validate that every entry-schema reference in the `.collection.json` files under
+ * `contentPath` exists in the registry. Run it at build time so a stale reference fails
+ * there rather than at runtime on first request.
  *
  * @example
  * ```typescript
@@ -160,7 +115,6 @@ export function createEntrySchemaRegistry(registry) {
 export async function validateEntrySchemaRegistry(entrySchemaRegistry, contentPath) {
     const { loadCollectionMetaFiles } = await import('./schema/index.js');
     const { access } = await import('fs/promises');
-    // Check if content directory exists
     try {
         await access(contentPath);
     }
@@ -170,11 +124,9 @@ export async function validateEntrySchemaRegistry(entrySchemaRegistry, contentPa
         }
         throw err;
     }
-    // Load all .collection.json files
     const metaFiles = await loadCollectionMetaFiles(contentPath);
     const availableSchemas = Object.keys(entrySchemaRegistry);
     const errors = [];
-    // Validate root entry type references
     if (metaFiles.root?.entries) {
         for (const entryType of metaFiles.root.entries) {
             if (!entrySchemaRegistry[entryType.schema]) {
@@ -183,7 +135,6 @@ export async function validateEntrySchemaRegistry(entrySchemaRegistry, contentPa
             }
         }
     }
-    // Validate collection entry type references
     for (const collection of metaFiles.collections) {
         if (collection.entries) {
             for (const entryType of collection.entries) {