@byline/core 3.20.4 → 3.21.0

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

@@ -1187,6 +1187,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/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/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';

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

@@ -0,0 +1,38 @@
+/**
+ * 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
+ */
+/** The persisted, unpopulated value of a relation field. */
+export interface RelatedDocumentValue {
+    targetDocumentId: string;
+    targetCollectionId: string;
+    relationshipType?: string;
+    cascadeDelete?: boolean;
+}
+/** A relation value that has not passed through population. */
+export interface UnpopulatedRelationValue extends RelatedDocumentValue {
+    _resolved?: never;
+    _cycle?: never;
+    document?: never;
+}
+/** Marker used when the target was already materialised in this read request. */
+export interface CycleRelationValue extends RelatedDocumentValue {
+    _resolved: true;
+    _cycle: true;
+}
+/** Marker used when the referenced target could not be read. */
+export interface UnresolvedRelationValue extends RelatedDocumentValue {
+    _resolved: false;
+}
+/** Relation envelope used when population successfully resolves the target. */
+export interface PopulatedRelationValue<TDocument = Record<string, any>> extends RelatedDocumentValue {
+    _resolved: true;
+    document: TDocument;
+}
+/** Every relation shape that can occur on the read path. */
+export type RelationReadValue<TDocument = Record<string, any>> = UnpopulatedRelationValue | PopulatedRelationValue<TDocument> | UnresolvedRelationValue | CycleRelationValue;
+/** Read shape for a single-target or `hasMany` relation field. */
+export type RelationFieldReadValue<HasMany extends boolean, TDocument = Record<string, any>> = HasMany extends true ? RelationReadValue<TDocument>[] : RelationReadValue<TDocument>;

package/dist/@types/relation-types.js

@@ -0,0 +1,8 @@
+/**
+ * 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
+ */
+export {};

package/dist/@types/site-config.d.ts

@@ -113,7 +113,7 @@ export interface BaseConfig {
          */
         translations?: TranslationBundleShape;
     };
-    collections: CollectionDefinition[];
+    collections: readonly CollectionDefinition[];
     /**
      * URL segments for admin and API routes. Both keys default to `/admin`
      * and `/api` respectively — installations only set this when they want

package/dist/codegen/fixtures/all-fields.d.ts

@@ -0,0 +1,342 @@
+export declare const QuoteBlock: {
+    readonly blockType: "quote'block";
+    readonly fields: readonly [{
+        readonly name: "quotation";
+        readonly type: "textArea";
+        readonly localized: true;
+    }, {
+        readonly name: "tone'choice";
+        readonly type: "select";
+        readonly optional: true;
+        readonly options: [{
+            readonly label: "Calm";
+            readonly value: "calm";
+        }, {
+            readonly label: "Quoted";
+            readonly value: "author's";
+        }];
+    }];
+};
+export declare const MediaBlock: {
+    readonly blockType: "media";
+    readonly fields: readonly [{
+        readonly name: "caption";
+        readonly type: "text";
+        readonly localized: true;
+        readonly optional: true;
+    }, {
+        readonly name: "image";
+        readonly type: "image";
+    }];
+};
+export declare const AllFieldsCollection: {
+    readonly path: "all-fields";
+    readonly labels: {
+        readonly singular: "All fields";
+        readonly plural: "All fields";
+    };
+    readonly fields: [{
+        readonly name: "integer";
+        readonly type: "integer";
+    }, {
+        readonly name: "float";
+        readonly type: "float";
+    }, {
+        readonly name: "counter";
+        readonly type: "counter";
+        readonly group: "fixture";
+    }, {
+        readonly name: "decimal";
+        readonly type: "decimal";
+    }, {
+        readonly name: "date";
+        readonly type: "date";
+    }, {
+        readonly name: "datetime";
+        readonly type: "datetime";
+    }, {
+        readonly name: "time";
+        readonly type: "time";
+    }, {
+        readonly name: "text";
+        readonly type: "text";
+    }, {
+        readonly name: "localizedText";
+        readonly type: "text";
+        readonly localized: true;
+    }, {
+        readonly name: "textArea";
+        readonly type: "textArea";
+    }, {
+        readonly name: "boolean";
+        readonly type: "boolean";
+    }, {
+        readonly name: "checkbox";
+        readonly type: "checkbox";
+    }, {
+        readonly name: "select";
+        readonly type: "select";
+        readonly options: [{
+            readonly label: "First";
+            readonly value: "first";
+        }, {
+            readonly label: "Second";
+            readonly value: "second's";
+        }];
+    }, {
+        readonly name: "json";
+        readonly type: "json";
+    }, {
+        readonly name: "localizedJson";
+        readonly type: "json";
+        readonly localized: true;
+    }, {
+        readonly name: "object";
+        readonly type: "object";
+    }, {
+        readonly name: "richText";
+        readonly type: "richText";
+    }, {
+        readonly name: "file";
+        readonly type: "file";
+    }, {
+        readonly name: "image";
+        readonly type: "image";
+    }, {
+        readonly name: "relation";
+        readonly type: "relation";
+        readonly targetCollection: "people";
+    }, {
+        readonly name: "relations";
+        readonly type: "relation";
+        readonly targetCollection: "people";
+        readonly hasMany: true;
+    }, {
+        readonly name: "optionalText";
+        readonly type: "text";
+        readonly optional: true;
+    }, {
+        readonly name: "group";
+        readonly type: "group";
+        readonly fields: readonly [{
+            readonly name: "title";
+            readonly type: "text";
+            readonly localized: true;
+        }, {
+            readonly name: "enabled";
+            readonly type: "boolean";
+            readonly optional: true;
+        }];
+    }, {
+        readonly name: "array";
+        readonly type: "array";
+        readonly fields: readonly [{
+            readonly name: "label";
+            readonly type: "text";
+            readonly localized: true;
+        }, {
+            readonly name: "score";
+            readonly type: "integer";
+            readonly optional: true;
+        }];
+    }, {
+        readonly name: "content's";
+        readonly type: "blocks";
+        readonly blocks: [{
+            readonly blockType: "quote'block";
+            readonly fields: readonly [{
+                readonly name: "quotation";
+                readonly type: "textArea";
+                readonly localized: true;
+            }, {
+                readonly name: "tone'choice";
+                readonly type: "select";
+                readonly optional: true;
+                readonly options: [{
+                    readonly label: "Calm";
+                    readonly value: "calm";
+                }, {
+                    readonly label: "Quoted";
+                    readonly value: "author's";
+                }];
+            }];
+        }, {
+            readonly blockType: "media";
+            readonly fields: readonly [{
+                readonly name: "caption";
+                readonly type: "text";
+                readonly localized: true;
+                readonly optional: true;
+            }, {
+                readonly name: "image";
+                readonly type: "image";
+            }];
+        }];
+    }];
+};
+export declare const MinimalCollection: {
+    readonly path: "minimal";
+    readonly labels: {
+        readonly singular: "Minimal";
+        readonly plural: "Minimal";
+    };
+    readonly fields: [{
+        readonly name: "title";
+        readonly type: "text";
+    }];
+};
+export declare const AllFieldsCollections: readonly [{
+    readonly path: "all-fields";
+    readonly labels: {
+        readonly singular: "All fields";
+        readonly plural: "All fields";
+    };
+    readonly fields: [{
+        readonly name: "integer";
+        readonly type: "integer";
+    }, {
+        readonly name: "float";
+        readonly type: "float";
+    }, {
+        readonly name: "counter";
+        readonly type: "counter";
+        readonly group: "fixture";
+    }, {
+        readonly name: "decimal";
+        readonly type: "decimal";
+    }, {
+        readonly name: "date";
+        readonly type: "date";
+    }, {
+        readonly name: "datetime";
+        readonly type: "datetime";
+    }, {
+        readonly name: "time";
+        readonly type: "time";
+    }, {
+        readonly name: "text";
+        readonly type: "text";
+    }, {
+        readonly name: "localizedText";
+        readonly type: "text";
+        readonly localized: true;
+    }, {
+        readonly name: "textArea";
+        readonly type: "textArea";
+    }, {
+        readonly name: "boolean";
+        readonly type: "boolean";
+    }, {
+        readonly name: "checkbox";
+        readonly type: "checkbox";
+    }, {
+        readonly name: "select";
+        readonly type: "select";
+        readonly options: [{
+            readonly label: "First";
+            readonly value: "first";
+        }, {
+            readonly label: "Second";
+            readonly value: "second's";
+        }];
+    }, {
+        readonly name: "json";
+        readonly type: "json";
+    }, {
+        readonly name: "localizedJson";
+        readonly type: "json";
+        readonly localized: true;
+    }, {
+        readonly name: "object";
+        readonly type: "object";
+    }, {
+        readonly name: "richText";
+        readonly type: "richText";
+    }, {
+        readonly name: "file";
+        readonly type: "file";
+    }, {
+        readonly name: "image";
+        readonly type: "image";
+    }, {
+        readonly name: "relation";
+        readonly type: "relation";
+        readonly targetCollection: "people";
+    }, {
+        readonly name: "relations";
+        readonly type: "relation";
+        readonly targetCollection: "people";
+        readonly hasMany: true;
+    }, {
+        readonly name: "optionalText";
+        readonly type: "text";
+        readonly optional: true;
+    }, {
+        readonly name: "group";
+        readonly type: "group";
+        readonly fields: readonly [{
+            readonly name: "title";
+            readonly type: "text";
+            readonly localized: true;
+        }, {
+            readonly name: "enabled";
+            readonly type: "boolean";
+            readonly optional: true;
+        }];
+    }, {
+        readonly name: "array";
+        readonly type: "array";
+        readonly fields: readonly [{
+            readonly name: "label";
+            readonly type: "text";
+            readonly localized: true;
+        }, {
+            readonly name: "score";
+            readonly type: "integer";
+            readonly optional: true;
+        }];
+    }, {
+        readonly name: "content's";
+        readonly type: "blocks";
+        readonly blocks: [{
+            readonly blockType: "quote'block";
+            readonly fields: readonly [{
+                readonly name: "quotation";
+                readonly type: "textArea";
+                readonly localized: true;
+            }, {
+                readonly name: "tone'choice";
+                readonly type: "select";
+                readonly optional: true;
+                readonly options: [{
+                    readonly label: "Calm";
+                    readonly value: "calm";
+                }, {
+                    readonly label: "Quoted";
+                    readonly value: "author's";
+                }];
+            }];
+        }, {
+            readonly blockType: "media";
+            readonly fields: readonly [{
+                readonly name: "caption";
+                readonly type: "text";
+                readonly localized: true;
+                readonly optional: true;
+            }, {
+                readonly name: "image";
+                readonly type: "image";
+            }];
+        }];
+    }];
+}, {
+    readonly path: "minimal";
+    readonly labels: {
+        readonly singular: "Minimal";
+        readonly plural: "Minimal";
+    };
+    readonly fields: [{
+        readonly name: "title";
+        readonly type: "text";
+    }];
+}];

package/dist/codegen/fixtures/all-fields.expected.d.ts

@@ -0,0 +1,120 @@
+import type { JsonObject, JsonValue, RelatedDocumentValue, StoredFileValue } from '@byline/core';
+export type MediaBlockData = {
+    _id: string;
+    _type: 'media';
+    caption?: string | undefined;
+    image: StoredFileValue;
+};
+export type MediaBlockDataAllLocales = {
+    _id: string;
+    _type: 'media';
+    caption?: {
+        [locale: string]: string;
+    } | undefined;
+    image: StoredFileValue;
+};
+export type QuoteBlockData = {
+    _id: string;
+    _type: "quote'block";
+    quotation: string;
+    "tone'choice"?: 'calm' | "author's" | undefined;
+};
+export type QuoteBlockDataAllLocales = {
+    _id: string;
+    _type: "quote'block";
+    quotation: {
+        [locale: string]: string;
+    };
+    "tone'choice"?: 'calm' | "author's" | undefined;
+};
+export type AllFieldsFields = {
+    integer: number;
+    float: number;
+    counter: number;
+    decimal: string;
+    date: Date;
+    datetime: Date;
+    time: string;
+    text: string;
+    localizedText: string;
+    textArea: string;
+    boolean: boolean;
+    checkbox: boolean;
+    select: 'first' | "second's";
+    json: JsonValue;
+    localizedJson: JsonValue;
+    object: JsonObject;
+    richText: JsonValue;
+    file: StoredFileValue;
+    image: StoredFileValue;
+    relation: RelatedDocumentValue;
+    relations: RelatedDocumentValue[];
+    optionalText?: string | undefined;
+    group: {
+        title: string;
+        enabled?: boolean | undefined;
+    };
+    array: Array<{
+        _id: string;
+        label: string;
+        score?: number | undefined;
+    }>;
+    "content's": Array<QuoteBlockData | MediaBlockData>;
+};
+export type AllFieldsFieldsAllLocales = {
+    integer: number;
+    float: number;
+    counter: number;
+    decimal: string;
+    date: Date;
+    datetime: Date;
+    time: string;
+    text: string;
+    localizedText: {
+        [locale: string]: string;
+    };
+    textArea: string;
+    boolean: boolean;
+    checkbox: boolean;
+    select: 'first' | "second's";
+    json: JsonValue;
+    localizedJson: {
+        [locale: string]: JsonValue;
+    };
+    object: JsonObject;
+    richText: JsonValue;
+    file: StoredFileValue;
+    image: StoredFileValue;
+    relation: RelatedDocumentValue;
+    relations: RelatedDocumentValue[];
+    optionalText?: string | undefined;
+    group: {
+        title: {
+            [locale: string]: string;
+        };
+        enabled?: boolean | undefined;
+    };
+    array: Array<{
+        _id: string;
+        label: {
+            [locale: string]: string;
+        };
+        score?: number | undefined;
+    }>;
+    "content's": Array<QuoteBlockDataAllLocales | MediaBlockDataAllLocales>;
+};
+export type MinimalFields = {
+    title: string;
+};
+export type MinimalFieldsAllLocales = {
+    title: string;
+};
+export type CollectionFieldsByPath = {
+    'all-fields': AllFieldsFields;
+    minimal: MinimalFields;
+};
+export type CollectionFieldsAllLocalesByPath = {
+    'all-fields': AllFieldsFieldsAllLocales;
+    minimal: MinimalFieldsAllLocales;
+};
+export type CollectionPath = keyof CollectionFieldsByPath;