@easy-cms/core 0.20.1 → 0.22.0

package/dist/index.d.ts

@@ -230,137 +230,6 @@ declare function consoleEmail(options?: {
     })[];
 };
 
-/** A label shown in the admin UI. Either one string or one string per admin locale. */
-type Label = string | {
-    readonly [locale: string]: string;
-};
-interface FieldValidateContext {
-    /** The whole document being validated, including sibling fields. */
-    readonly data: Readonly<Record<string, unknown>>;
-    readonly operation: 'create' | 'update';
-}
-/** Return `true` when valid, or an error message to show on the field. */
-type FieldValidate<TValue> = (value: TValue | null | undefined, ctx: FieldValidateContext) => true | string | Promise<true | string>;
-/**
- * A Web Component from an admin module (`admin.modules`), by its tag name, which must start
- * with `ecms-`. `props` (plain JSON) reach the element as its `options` property.
- */
-type AdminComponent = string | {
-    readonly tag: string;
-    readonly props?: Readonly<Record<string, unknown>>;
-};
-/** How the admin shows a field, with components from admin modules. */
-interface FieldAdmin {
-    /** Shown instead of the field's input; the admin keeps the label and error messages. */
-    readonly component?: AdminComponent;
-    /** Shown below the field, e.g. a length meter or a preview. */
-    readonly after?: readonly AdminComponent[];
-}
-interface BaseField<TType extends string, TValue> {
-    readonly type: TType;
-    readonly name: string;
-    readonly label?: Label;
-    readonly required?: boolean;
-    readonly unique?: boolean;
-    readonly index?: boolean;
-    readonly defaultValue?: TValue;
-    readonly validate?: FieldValidate<TValue>;
-    readonly access?: FieldAccess;
-    /** Stored but never returned by the API nor accepted as input (e.g. a password hash). */
-    readonly hidden?: boolean;
-    /**
-     * One value per locale (needs `localization` in the config). Not for groups, arrays or
-     * hasMany fields: localize the fields inside a group or array instead.
-     */
-    readonly localized?: boolean;
-    /** `sidebar`: shown in the edit page's side panel instead of the main form (top-level fields). */
-    readonly position?: 'sidebar';
-    /** Custom admin components for this field. */
-    readonly admin?: FieldAdmin;
-}
-interface TextField extends BaseField<'text', string> {
-    readonly minLength?: number;
-    readonly maxLength?: number;
-}
-interface TextareaField extends BaseField<'textarea', string> {
-    readonly minLength?: number;
-    readonly maxLength?: number;
-}
-interface NumberField extends BaseField<'number', number> {
-    readonly min?: number;
-    readonly max?: number;
-}
-interface BooleanField extends BaseField<'boolean', boolean> {
-}
-/** Stored and returned as an ISO 8601 string. */
-interface DateField extends BaseField<'date', string> {
-}
-interface EmailField extends BaseField<'email', string> {
-}
-interface JsonField extends BaseField<'json', unknown> {
-}
-type SelectOption = string | {
-    readonly label: Label;
-    readonly value: string;
-};
-interface SelectField extends BaseField<'select', string | readonly string[]> {
-    readonly options: readonly SelectOption[];
-    readonly hasMany?: boolean;
-}
-interface SlugField extends BaseField<'slug', string> {
-    /** Name of a sibling `text` field to generate the slug from. */
-    readonly from?: string;
-}
-/** Tiptap / ProseMirror JSON document. */
-interface RichTextDocument {
-    readonly type: 'doc';
-    readonly content?: readonly unknown[];
-}
-interface RichTextField extends BaseField<'richText', RichTextDocument> {
-}
-/** References a document in the built-in `media` collection. */
-interface UploadField extends BaseField<'upload', never> {
-}
-interface RelationshipField extends BaseField<'relationship', never> {
-    /** Slug of the target collection. */
-    readonly to: string;
-    readonly hasMany?: boolean;
-}
-interface ArrayField extends BaseField<'array', never> {
-    readonly fields: readonly Field[];
-    readonly minRows?: number;
-    readonly maxRows?: number;
-}
-interface GroupField extends BaseField<'group', never> {
-    readonly fields: readonly Field[];
-}
-/** One kind of block in a `blocks` field. */
-interface Block {
-    /** Stored in each row as `blockType`. */
-    readonly slug: string;
-    readonly labels?: {
-        readonly singular?: Label;
-        readonly plural?: Label;
-    };
-    readonly fields: readonly Field[];
-}
-/**
- * A list of rows, each one of several block kinds (e.g. hero, text, gallery), for pages that
- * editors lay out themselves. Rows are `{ id, blockType, ...fields }`, stored as JSON.
- */
-interface BlocksField extends BaseField<'blocks', never> {
-    readonly blocks: readonly Block[];
-    readonly minRows?: number;
-    readonly maxRows?: number;
-}
-/** Fields whose value is a list of rows: `array` and `blocks`. */
-declare const hasRows: (field: Field) => field is ArrayField | BlocksField;
-/** The fields of one row of an `array` or `blocks` field (`undefined` for an unknown block). */
-declare function rowFields(field: ArrayField | BlocksField, row: unknown): readonly Field[] | undefined;
-type Field = TextField | TextareaField | NumberField | BooleanField | DateField | EmailField | JsonField | SelectField | SlugField | RichTextField | UploadField | RelationshipField | ArrayField | GroupField | BlocksField;
-type FieldType = Field['type'];
-declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group", "blocks"];
-
 /** What a preview token opens: one document of a collection, or one global. */
 type PreviewTarget = {
     readonly collection: string;
@@ -757,6 +626,14 @@ interface DepthOptions extends AccessOptions {
      */
     readonly locale?: string;
 }
+interface UpdateOptions extends DepthOptions {
+    /**
+     * Upkeep of the live document, e.g. values a plugin keeps up to date (a page's path): with
+     * drafts and versions a pending draft stays as it is (edits go to it by default), the status
+     * stays, and no version is added to the history.
+     */
+    readonly live?: boolean;
+}
 interface ReadOptions extends DepthOptions {
     /**
      * Include drafts. By default only published documents of collections with
@@ -846,7 +723,7 @@ declare class EasyCMS<C extends Config = Config> {
     }>;
     /** Public URL of a stored file. */
     mediaURL(key: string): string;
-    update<S extends Slug<C>>(collection: S, id: ID, data: Update<C, S>, options?: DepthOptions): Promise<Doc<C, S>>;
+    update<S extends Slug<C>>(collection: S, id: ID, data: Update<C, S>, options?: UpdateOptions): Promise<Doc<C, S>>;
     /**
      * Takes a document off the site: its status becomes `draft`. With versions and drafts, a plain
      * `update` with `status: 'draft'` only saves a draft and leaves the published document live;
@@ -1056,6 +933,8 @@ declare class EasyCMS<C extends Config = Config> {
     private makeSlugsUnique;
     private checkUnique;
     private isTaken;
+    /** Each reference is one its relationship's `filterOptions` allow. */
+    private checkFilterOptions;
     private checkReferences;
 }
 /** A document as live preview shows it, and the page to show it on. */
@@ -1065,6 +944,154 @@ interface LivePreview<T> {
     readonly url: string | null;
 }
 
+/** A label shown in the admin UI. Either one string or one string per admin locale. */
+type Label = string | {
+    readonly [locale: string]: string;
+};
+interface FieldValidateContext {
+    /** The whole document being validated, including sibling fields. */
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly operation: 'create' | 'update';
+}
+/** Return `true` when valid, or an error message to show on the field. */
+type FieldValidate<TValue> = (value: TValue | null | undefined, ctx: FieldValidateContext) => true | string | Promise<true | string>;
+/**
+ * A Web Component from an admin module (`admin.modules`), by its tag name, which must start
+ * with `ecms-`. `props` (plain JSON) reach the element as its `options` property.
+ */
+type AdminComponent = string | {
+    readonly tag: string;
+    readonly props?: Readonly<Record<string, unknown>>;
+};
+/** How the admin shows a field, with components from admin modules. */
+interface FieldAdmin {
+    /** Shown instead of the field's input; the admin keeps the label and error messages. */
+    readonly component?: AdminComponent;
+    /** Shown below the field, e.g. a length meter or a preview. */
+    readonly after?: readonly AdminComponent[];
+}
+interface BaseField<TType extends string, TValue> {
+    readonly type: TType;
+    readonly name: string;
+    readonly label?: Label;
+    readonly required?: boolean;
+    readonly unique?: boolean;
+    readonly index?: boolean;
+    readonly defaultValue?: TValue;
+    readonly validate?: FieldValidate<TValue>;
+    readonly access?: FieldAccess;
+    /** Stored but never returned by the API nor accepted as input (e.g. a password hash). */
+    readonly hidden?: boolean;
+    /**
+     * One value per locale (needs `localization` in the config). Not for groups, arrays or
+     * hasMany fields: localize the fields inside a group or array instead.
+     */
+    readonly localized?: boolean;
+    /** `sidebar`: shown in the edit page's side panel instead of the main form (top-level fields). */
+    readonly position?: 'sidebar';
+    /** Custom admin components for this field. */
+    readonly admin?: FieldAdmin;
+}
+interface TextField extends BaseField<'text', string> {
+    readonly minLength?: number;
+    readonly maxLength?: number;
+}
+interface TextareaField extends BaseField<'textarea', string> {
+    readonly minLength?: number;
+    readonly maxLength?: number;
+}
+interface NumberField extends BaseField<'number', number> {
+    readonly min?: number;
+    readonly max?: number;
+}
+interface BooleanField extends BaseField<'boolean', boolean> {
+}
+/** Stored and returned as an ISO 8601 string. */
+interface DateField extends BaseField<'date', string> {
+}
+interface EmailField extends BaseField<'email', string> {
+}
+interface JsonField extends BaseField<'json', unknown> {
+}
+type SelectOption = string | {
+    readonly label: Label;
+    readonly value: string;
+};
+interface SelectField extends BaseField<'select', string | readonly string[]> {
+    readonly options: readonly SelectOption[];
+    readonly hasMany?: boolean;
+}
+interface SlugField extends BaseField<'slug', string> {
+    /** Name of a sibling `text` field to generate the slug from. */
+    readonly from?: string;
+    /**
+     * Name of a sibling field (e.g. `parent`): slugs then only need to differ among documents
+     * with the same value there, so `/about/team` and `/careers/team` can both be `team`.
+     */
+    readonly uniqueWithin?: string;
+}
+/** Tiptap / ProseMirror JSON document. */
+interface RichTextDocument {
+    readonly type: 'doc';
+    readonly content?: readonly unknown[];
+}
+interface RichTextField extends BaseField<'richText', RichTextDocument> {
+}
+/** References a document in the built-in `media` collection. */
+interface UploadField extends BaseField<'upload', never> {
+}
+interface FilterOptionsArgs {
+    /** The document being edited; `undefined` while it is being created. */
+    readonly id: ID | undefined;
+    readonly user: AuthUser | null;
+    readonly cms: EasyCMS;
+}
+/**
+ * Which documents a relationship may point to: a `where` on the target collection, or `true`
+ * for any. Runs on the server: the admin's picker offers only these, and saving checks them.
+ */
+type FilterOptions = (args: FilterOptionsArgs) => Where | true | Promise<Where | true>;
+interface RelationshipField extends BaseField<'relationship', never> {
+    /** Slug of the target collection. */
+    readonly to: string;
+    readonly hasMany?: boolean;
+    readonly filterOptions?: FilterOptions;
+}
+interface ArrayField extends BaseField<'array', never> {
+    readonly fields: readonly Field[];
+    readonly minRows?: number;
+    readonly maxRows?: number;
+}
+interface GroupField extends BaseField<'group', never> {
+    readonly fields: readonly Field[];
+}
+/** One kind of block in a `blocks` field. */
+interface Block {
+    /** Stored in each row as `blockType`. */
+    readonly slug: string;
+    readonly labels?: {
+        readonly singular?: Label;
+        readonly plural?: Label;
+    };
+    readonly fields: readonly Field[];
+}
+/**
+ * A list of rows, each one of several block kinds (e.g. hero, text, gallery), for pages that
+ * editors lay out themselves. Rows are `{ id, blockType, ...fields }`, stored as JSON.
+ */
+interface BlocksField extends BaseField<'blocks', never> {
+    readonly blocks: readonly Block[];
+    readonly minRows?: number;
+    readonly maxRows?: number;
+}
+/** Fields whose value is a list of rows: `array` and `blocks`. */
+declare const hasRows: (field: Field) => field is ArrayField | BlocksField;
+/** The fields of one row of an `array` or `blocks` field (`undefined` for an unknown block). */
+declare function rowFields(field: ArrayField | BlocksField, row: unknown): readonly Field[] | undefined;
+type Field = TextField | TextareaField | NumberField | BooleanField | DateField | EmailField | JsonField | SelectField | SlugField | RichTextField | UploadField | RelationshipField | ArrayField | GroupField | BlocksField;
+type FieldType = Field['type'];
+declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group", "blocks"];
+
 declare const WEBHOOK_EVENTS: readonly ["create", "update", "delete", "publish", "unpublish", "draft"];
 /**
  * `create`, `update`, `delete`: the stored document changed. `publish` / `unpublish`: its status
@@ -1179,6 +1206,16 @@ interface CollectionAdmin extends ContainerAdmin {
      * instead of with the content, e.g. for redirects or forms settings.
      */
     readonly group?: 'settings';
+    readonly list?: CollectionListAdmin;
+}
+interface CollectionListAdmin {
+    /**
+     * Show the list as a tree: the name of a relationship field to this same collection (e.g.
+     * `parent`). Top-level documents come first; their children open below them.
+     */
+    readonly tree?: string;
+    /** The list's default order, e.g. `title` or `-updatedAt` (the default). */
+    readonly sort?: string;
 }
 interface CollectionConfig {
     /** URL and table name. Lowercase letters, digits, `-` and `_`. */
@@ -1330,6 +1367,22 @@ interface EndpointRequest {
  * A custom REST endpoint, served under `routes.api`. Writes from the browser pass the same
  * CSRF check as the built-in endpoints.
  */
+/** An `easy-cms <name> [args…]` command. Built-in commands keep their names. */
+interface CliCommand {
+    /** Lowercase, e.g. `nested:rebuild`. */
+    readonly name: string;
+    /** One line for `easy-cms --help`. */
+    readonly description: string;
+    /** Shown by `easy-cms <name> --help`. */
+    readonly help?: string;
+    /** Runs with the CMS open (no schema push); return a non-zero exit code on failure. */
+    readonly run: (args: {
+        readonly cms: EasyCMS;
+        /** Positional arguments after the command name. */
+        readonly args: readonly string[];
+        readonly log: (line: string) => void;
+    }) => MaybePromise<number | undefined>;
+}
 interface Endpoint {
     /**
      * Path under the API, e.g. `/seo/generate` or `/stats/:collection`. The first segment must
@@ -1389,6 +1442,8 @@ interface Config {
     readonly globals?: readonly GlobalConfig[];
     /** Custom REST endpoints, e.g. from plugins. */
     readonly endpoints?: readonly Endpoint[];
+    /** Extra `easy-cms <name>` CLI commands, e.g. from plugins. */
+    readonly commands?: readonly CliCommand[];
     /**
      * API keys for scripts and other apps (`Authorization: Bearer ecms_…`), managed in the admin
      * under Settings. A key acts as its owner, limited to the collections and operations it lists.
@@ -1414,6 +1469,7 @@ interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes'
     readonly collections: readonly CollectionConfig[];
     readonly globals: readonly GlobalConfig[];
     readonly endpoints: readonly Endpoint[];
+    readonly commands: readonly CliCommand[];
 }
 /**
  * Declares the Easy CMS config. Returns it unchanged, keeping literal types
@@ -1565,6 +1621,8 @@ interface Reference {
     readonly field: string;
     readonly collection: string;
     readonly id: ID;
+    /** The relationship's `filterOptions`, checked when saving. */
+    readonly filterOptions?: FilterOptions;
 }
 interface ValidateOptions {
     readonly operation: 'create' | 'update';
@@ -1674,6 +1732,8 @@ interface AdminField {
     }[];
     hasMany?: boolean;
     to?: string;
+    /** A relationship with `filterOptions`: the picker asks the server which documents fit. */
+    filtered?: boolean;
     from?: string;
     minRows?: number;
     maxRows?: number;
@@ -1720,6 +1780,10 @@ interface AdminCollection {
     sidebar?: AdminComponentRef[];
     /** Listed under Settings in the menu (users, API keys, `admin.group: 'settings'`). */
     group?: 'settings';
+    /** The list is a tree along this relationship field (`admin.list.tree`). */
+    tree?: string;
+    /** The list's default order (`admin.list.sort`). */
+    defaultSort?: string;
     permissions: {
         read: boolean;
         create: boolean;
@@ -1795,4 +1859,4 @@ declare const BUILTIN_COLLECTIONS: readonly ["users", "media"];
 /** Checks a config and returns every problem found. An empty array means it is valid. */
 declare function validateConfig(config: Config): ConfigIssue[];
 
-export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailField, type EmailMessage, type Endpoint, type EndpointRequest, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, PayloadTooLargeError, type Plugin, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailField, type EmailMessage, type Endpoint, type EndpointRequest, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, PayloadTooLargeError, type Plugin, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };

package/dist/index.js

@@ -1240,7 +1240,12 @@ async function normalizeValue(field, raw, path, options, fail, errors, reference
         if (id === void 0)
           return fail(`must be ${many ? "ids" : "an id"} of "${target}" documents`);
         ids.push(id);
-        references.push({ field: path, collection: target, id });
+        references.push({
+          field: path,
+          collection: target,
+          id,
+          ...field.type === "relationship" && field.filterOptions ? { filterOptions: field.filterOptions } : {}
+        });
       }
       return many ? ids : ids[0];
     }
@@ -1673,6 +1678,7 @@ function validateConfig(config) {
     checkSlug(global2, `globals[${i}]`, seenGlobals, add);
   });
   validateEndpoints(config, collectionSlugs, add);
+  validateCommands(config, add);
   const apiKeys = config.apiKeys;
   if (apiKeys !== void 0 && typeof apiKeys !== "boolean") add("apiKeys", "must be true or false");
   collections.forEach((collection2, i) => {
@@ -1997,6 +2003,8 @@ function validateContainer(container, path, collectionSlugs, add) {
       const group = admin.group;
       if (group !== void 0 && group !== "settings")
         add(`${path}.admin.group`, `must be 'settings' (got ${JSON.stringify(group)})`);
+      const list = admin.list;
+      if (list !== void 0) validateList(list, container, `${path}.admin.list`, add);
     }
   }
   const reserved = new Set(SYSTEM_FIELD_NAMES);
@@ -2034,6 +2042,24 @@ function validateFields2(fields, path, reserved, collectionSlugs, add) {
     validateField(field, fieldPath, byName, collectionSlugs, add);
   }
 }
+function validateList(list, container, path, add) {
+  if (typeof list !== "object" || list === null) {
+    add(path, "must be an object", "e.g. list: { tree: 'parent' }");
+    return;
+  }
+  const { tree, sort } = list;
+  if (sort !== void 0 && (typeof sort !== "string" || !sort.replace(/^-/, "")))
+    add(`${path}.sort`, "must be a field name, with - for descending", "e.g. sort: 'title'");
+  if (tree === void 0) return;
+  const field = container.fields.find((f) => f.name === tree);
+  if (field?.type !== "relationship" || field.to !== container.slug || field.hasMany || field.localized) {
+    add(
+      `${path}.tree`,
+      `must name a relationship field to "${container.slug}" (not hasMany or localized)`,
+      `e.g. { name: 'parent', type: 'relationship', to: '${container.slug}' }`
+    );
+  }
+}
 function validateField(field, path, siblings, collectionSlugs, add) {
   const position = field.position;
   if (position !== void 0 && position !== "sidebar") {
@@ -2069,6 +2095,17 @@ function validateField(field, path, siblings, collectionSlugs, add) {
           add(`${path}.from`, `"${field.from}" must be a text field (got ${source.type})`);
         }
       }
+      if (field.uniqueWithin !== void 0) {
+        const scope = siblings.get(field.uniqueWithin);
+        if (!scope || scope === field) {
+          add(`${path}.uniqueWithin`, `no sibling field named "${field.uniqueWithin}"`);
+        } else if (!["relationship", "select", "text", "number"].includes(scope.type) || "hasMany" in scope && scope.hasMany || scope.localized) {
+          add(
+            `${path}.uniqueWithin`,
+            `"${field.uniqueWithin}" must be a single, unlocalized relationship, select, text or number field`
+          );
+        }
+      }
       break;
     case "relationship":
       if (typeof field.to !== "string" || !collectionSlugs.has(field.to)) {
@@ -2157,6 +2194,25 @@ function validateComponents(components, path, add) {
 var ENDPOINT_METHODS = ["get", "post", "put", "patch", "delete"];
 var ENDPOINT_SEGMENT = /^(:[A-Za-z_][A-Za-z0-9_]*|[A-Za-z0-9._~-]+)$/;
 var RESERVED_ENDPOINT_ROOTS = /* @__PURE__ */ new Set(["users", "globals", "admin", "jobs", "media", "api-keys"]);
+function validateCommands(config, add) {
+  const commands = config.commands;
+  if (commands === void 0) return;
+  if (!Array.isArray(commands)) {
+    add("commands", "must be an array", "e.g. commands: [{ name: 'my:task', description, run }]");
+    return;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  commands.forEach((command, i) => {
+    const path = `commands[${i}]`;
+    const { name, description, run } = command ?? {};
+    if (typeof name !== "string" || !/^[a-z][a-z0-9-]*(:[a-z0-9-]+)*$/.test(name))
+      add(`${path}.name`, "must be lowercase letters, digits, - and :", "e.g. 'nested:rebuild'");
+    else if (seen.has(name)) add(`${path}.name`, `"${name}" is already used by another command`);
+    else seen.add(name);
+    if (typeof description !== "string") add(`${path}.description`, "must be a string");
+    if (typeof run !== "function") add(`${path}.run`, "must be a function");
+  });
+}
 function validateEndpoints(config, collectionSlugs, add) {
   const endpoints = config.endpoints;
   if (endpoints === void 0) return;
@@ -2323,7 +2379,8 @@ async function resolveConfig(input) {
       ...config.email ? [emailDeliveriesCollection] : []
     ],
     globals: config.globals ?? [],
-    endpoints: config.endpoints ?? []
+    endpoints: config.endpoints ?? [],
+    commands: config.commands ?? []
   };
   resolved.add(result);
   return result;
@@ -2368,7 +2425,7 @@ async function loadConfig(options = {}) {
     const looked = options.configFile ?? CONFIG_FILE_NAMES.join(", ");
     throw new Error(
       `Easy CMS config not found in ${cwd} (looked for ${looked}).
-    \u2192 run \`npx create-easy-cms\` to create one`
+    \u2192 create one with create-easy-cms (\`npm create easy-cms\`, or pnpm, yarn or bun create easy-cms)`
     );
   }
   const jiti = createJiti(import.meta.url, { moduleCache: false, interopDefault: false });
@@ -3269,7 +3326,13 @@ var EasyCMS = class {
     await this.checkDocumentAccess(config, "update", guard, parsed, raw);
     if (config.drafts && (mode === "unpublish" || raw.status === "published"))
       this.checkKey(guard, { collection: collection2 }, "publish");
-    const [current] = await this.withDrafts(config, [existing]);
+    const [drafted] = await this.withDrafts(config, [existing]);
+    const live = options.live === true && mode === "save";
+    const current = live ? existing : drafted;
+    if (live && Object.hasOwn(raw, "status")) {
+      const { status: _status, ...rest } = raw;
+      raw = rest;
+    }
     const { input, password } = splitPassword(config, raw);
     const filtered = await filterInput(
       config.fields,
@@ -3292,7 +3355,8 @@ var EasyCMS = class {
       generateSlugs(config.fields, merged, this.config.localization),
       "update",
       parsed,
-      options
+      options,
+      guard.user
     );
     prepared = await this.transform(
       config.hooks?.beforeChange,
@@ -3329,7 +3393,7 @@ var EasyCMS = class {
       id: parsed,
       data: { ...prepared, createdAt: existing.createdAt, updatedAt: now }
     });
-    await this.saveVersion(config, collectionParent(collection2), parsed, doc, guard);
+    if (!live) await this.saveVersion(config, collectionParent(collection2), parsed, doc, guard);
     if (password !== void 0) await this.auth.revokeSessions(parsed);
     await this.notify(config.hooks?.afterChange, "afterChange", config.slug, {
       ...base,
@@ -3476,7 +3540,7 @@ var EasyCMS = class {
     );
     if (config.drafts) merged.status = input.status ?? current.status ?? "draft";
     const base = this.hookArgs(config, guard);
-    let prepared = await this.prepare(config, merged, "update", void 0, options);
+    let prepared = await this.prepare(config, merged, "update", void 0, options, guard.user);
     prepared = await this.transform(
       config.hooks?.beforeChange,
       "data",
@@ -3969,7 +4033,8 @@ var EasyCMS = class {
       generateSlugs(config.fields, data, this.config.localization),
       "create",
       void 0,
-      options
+      options,
+      (hookGuard ?? guard).user
     );
     prepared = await this.transform(
       config.hooks?.beforeChange,
@@ -4139,7 +4204,7 @@ var EasyCMS = class {
     return result;
   }
   /** Validates, checks uniqueness and references. Returns clean data or throws `ValidationError`. */
-  async prepare(config, data, operation, selfId, options = {}) {
+  async prepare(config, data, operation, selfId, options = {}, user = null) {
     const isDraft = config.drafts === true && (data.status ?? "draft") === "draft";
     const locale = this.localeOf(options);
     const result = await validateFields(config.fields, data, {
@@ -4164,6 +4229,8 @@ var EasyCMS = class {
       errors.push(...await this.checkUnique(config, clean, selfId));
     }
     errors.push(...await this.checkReferences(result.references));
+    if (errors.length === 0)
+      errors.push(...await this.checkFilterOptions(result.references, selfId, user));
     if (errors.length > 0) throw new ValidationError(config.slug, errors);
     return clean;
   }
@@ -4189,15 +4256,16 @@ var EasyCMS = class {
     }
   }
   async makeSlugsUnique(config, data, selfId) {
-    const unique = async (path, base) => {
-      let candidate = base;
-      for (let n = 2; await this.isTaken(config.slug, path, candidate, selfId); n++) {
-        candidate = `${base}-${n}`;
-      }
-      return candidate;
-    };
     for (const field of config.fields) {
       if (field.type !== "slug") continue;
+      const scope = field.uniqueWithin === void 0 ? void 0 : { [field.uniqueWithin]: { equals: data[field.uniqueWithin] ?? null } };
+      const unique = async (path, base) => {
+        let candidate = base;
+        for (let n = 2; await this.isTaken(config.slug, path, candidate, selfId, scope); n++) {
+          candidate = `${base}-${n}`;
+        }
+        return candidate;
+      };
       const value = data[field.name];
       if (field.localized && value && typeof value === "object") {
         const map = { ...value };
@@ -4230,10 +4298,39 @@ var EasyCMS = class {
     }
     return errors;
   }
-  async isTaken(collection2, field, value, selfId) {
-    const where = selfId === void 0 ? { [field]: { equals: value } } : { and: [{ [field]: { equals: value } }, { id: { not_equals: selfId } }] };
+  async isTaken(collection2, field, value, selfId, scope) {
+    const where = {
+      and: [
+        { [field]: { equals: value } },
+        ...selfId === void 0 ? [] : [{ id: { not_equals: selfId } }],
+        ...scope ? [scope] : []
+      ]
+    };
     return await this.db.count({ collection: collection2, where }) > 0;
   }
+  /** Each reference is one its relationship's `filterOptions` allow. */
+  async checkFilterOptions(references, selfId, user) {
+    const errors = [];
+    const cms = this;
+    const allowed2 = /* @__PURE__ */ new Map();
+    for (const ref of references) {
+      const filter = ref.filterOptions;
+      if (!filter) continue;
+      if (!allowed2.has(filter)) allowed2.set(filter, await filter({ id: selfId, user, cms }));
+      const where = allowed2.get(filter);
+      if (where === true) continue;
+      const target = this.config.collections.find((c) => c.slug === ref.collection);
+      const localization = this.config.localization;
+      const scoped = target ? this.whereFor(target, where, localization ? { locale: localization.defaultLocale } : {}) : where;
+      const count = await this.db.count({
+        collection: ref.collection,
+        where: { and: [{ id: { equals: ref.id } }, ...scoped ? [scoped] : []] }
+      });
+      if (count === 0)
+        errors.push({ field: ref.field, message: "is not one of the allowed choices" });
+    }
+    return errors;
+  }
   async checkReferences(references) {
     const byCollection = /* @__PURE__ */ new Map();
     for (const ref of references) {
@@ -4395,6 +4492,7 @@ async function serializeFields(fields, update, localized) {
       case "relationship":
         f.to = field.to;
         if (field.hasMany) f.hasMany = true;
+        if (field.filterOptions) f.filtered = true;
         break;
       case "upload":
         f.to = "media";
@@ -4447,6 +4545,8 @@ async function collection(config, user, localized) {
   if (config.icon) result.icon = config.icon;
   if (config.admin?.sidebar?.length) result.sidebar = config.admin.sidebar.map(componentRef);
   if (config.admin?.group === "settings" || SETTINGS.has(config.slug)) result.group = "settings";
+  if (config.admin?.list?.tree) result.tree = config.admin.list.tree;
+  if (config.admin?.list?.sort) result.defaultSort = config.admin.list.sort;
   if (config.editIn === "drawer" && !result.drafts && !result.versions && !result.preview)
     result.editIn = "drawer";
   return result;
@@ -4487,6 +4587,36 @@ async function adminSchema(cms, user) {
   };
 }
 
+// src/rest/filter-options.ts
+function fieldAt(fields, path) {
+  let current = fields;
+  let found;
+  for (const part of path.split(".")) {
+    if (/^\d+$/.test(part)) continue;
+    found = current?.find((f) => f.name === part);
+    if (!found) return void 0;
+    current = found.type === "array" || found.type === "group" ? found.fields : void 0;
+  }
+  return found;
+}
+async function pickerFilter(cms, url, target, user) {
+  const forCollection = url.searchParams.get("filterFor");
+  const forGlobal = url.searchParams.get("filterForGlobal");
+  const spec = forCollection ?? forGlobal;
+  if (spec === null) return void 0;
+  const dot = spec.indexOf(".");
+  const slug = dot > 0 ? spec.slice(0, dot) : "";
+  const owner = forCollection !== null ? cms.config.collections.find((c) => c.slug === slug) : cms.config.globals.find((g) => g.slug === slug);
+  const field = owner ? fieldAt(owner.fields, spec.slice(dot + 1)) : void 0;
+  if (field?.type !== "relationship" || field.to !== target)
+    throw new QueryError(`filterFor: no relationship to "${target}" at "${spec}"`);
+  if (!field.filterOptions) return void 0;
+  const rawId = url.searchParams.get("filterId");
+  const id = rawId === null || rawId === "" ? void 0 : /^\d+$/.test(rawId) ? Number(rawId) : rawId;
+  const where = await field.filterOptions({ id, user, cms });
+  return where === true ? void 0 : where;
+}
+
 // src/rest/query.ts
 var MAX_DEPTH2 = 10;
 var MAX_INDEX = 100;
@@ -4879,6 +5009,8 @@ async function route(cms, ctx, method, segments, options) {
   if (second === void 0) {
     if (method === "GET") {
       const query = parseListQuery(ctx.url);
+      const filter = await pickerFilter(cms, ctx.url, collection2, ctx.user);
+      if (filter) query.where = query.where ? { and: [query.where, filter] } : filter;
       return { body: await cms.find(collection2, { ...access, ...query, draft }) };
     }
     if (method === "POST") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easy-cms/core",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "description": "Embedded, code-first headless CMS for Nuxt and Next.js",
   "license": "MIT",
   "type": "module",