@easy-cms/core 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -439,16 +439,41 @@ interface BuiltinApiKeysCollection {
 type ApiKeysOf<C extends Config> = C extends {
     readonly apiKeys: true;
 } ? BuiltinApiKeysCollection : never;
-/** Every collection of a config, including the built-in ones. */
-type AllCollections<C extends Config> = NonNullable<C['collections']>[number] | BuiltinUsersCollection | BuiltinMediaCollection | ApiKeysOf<C>;
+/** The `PluginTypes` of each plugin in the config (a union). */
+type PluginTypesOf<C extends Config> = C extends {
+    readonly plugins: readonly (infer P)[];
+} ? P extends TypedPlugin<infer T extends PluginTypes> ? T : never : never;
+/** Fields that plugins add to the collection (or global) `S`, as a union. */
+type AddedFields<T, S> = T extends {
+    readonly [K in 'fields' | 'globalFields']?: infer M;
+} ? M extends {
+    readonly [slug: string]: readonly Field[];
+} ? string extends keyof M ? never : S extends keyof M ? M[S][number] : never : never : never;
+type PluginFields<C extends Config, S, Key extends 'fields' | 'globalFields'> = AddedFields<PluginTypesOf<C> extends infer T ? T extends PluginTypes ? Pick<T, Key & keyof T> : never : never, S>;
+/** Collections that plugins add. */
+type PluginCollections<C extends Config> = PluginTypesOf<C> extends infer T ? T extends {
+    readonly collections: readonly (infer K extends CollectionConfig)[];
+} ? K : never : never;
+/** A collection or global with the fields plugins add to it. */
+type WithPluginFields<C extends Config, T extends {
+    readonly slug: string;
+    readonly fields: readonly Field[];
+}, Key extends 'fields' | 'globalFields'> = [PluginFields<C, T['slug'], Key>] extends [never] ? T : Omit<T, 'fields'> & {
+    readonly fields: readonly (T['fields'][number] | PluginFields<C, T['slug'], Key>)[];
+};
+/** Every collection of a config, including the built-in ones and those plugins add. */
+type AllCollections<C extends Config> = NonNullable<C['collections']>[number] | BuiltinUsersCollection | BuiltinMediaCollection | ApiKeysOf<C> | PluginCollections<C>;
 /** The built-in media collection; its documents are typed as `MediaDocument`. */
 interface BuiltinMediaCollection {
     readonly slug: 'media';
     readonly fields: readonly [];
 }
-type CollectionBySlug<C extends Config, S> = Extract<AllCollections<C>, {
+type CollectionBySlug<C extends Config, S> = WithPluginFields<C, Extract<AllCollections<C>, {
     readonly slug: S;
-}>;
+}>, 'fields'>;
+type GlobalBySlug<C extends Config, S> = WithPluginFields<C, Extract<NonNullable<C['globals']>[number], {
+    readonly slug: S;
+}>, 'globalFields'>;
 /** Relationships are ids at depth 0 and documents when populated. */
 type RelationValue<C extends Config, S> = [CollectionBySlug<C, S>] extends [never] ? ID | Record<string, unknown> : ID | CollectionDocument<C, S & string>;
 interface MediaSize {
@@ -544,7 +569,7 @@ type FieldsValue<Fs extends readonly Field[], C extends Config = Config> = Simpl
     -readonly [F in OptionalFields<Fs> as F['name']]?: FieldValue<F, C> | null;
 }>;
 type SystemFields<T extends {
-    readonly drafts?: boolean;
+    readonly drafts?: unknown;
 }> = {
     id: ID;
     createdAt: string;
@@ -554,8 +579,13 @@ type SystemFields<T extends {
 } ? {
     status: 'draft' | 'published';
 } : unknown);
-type InferCollection<T extends CollectionConfig, C extends Config = Config> = Simplify<SystemFields<T> & FieldsValue<T['fields'], C>>;
-type InferGlobal<T extends GlobalConfig, C extends Config = Config> = Simplify<
+/** What document types are inferred from: a collection's or global's fields and drafts. */
+type FieldsOwner = {
+    readonly fields: readonly Field[];
+    readonly drafts?: unknown;
+};
+type InferCollection<T extends FieldsOwner, C extends Config = Config> = Simplify<SystemFields<T> & FieldsValue<T['fields'], C>>;
+type InferGlobal<T extends FieldsOwner, C extends Config = Config> = Simplify<
 /** `null` until the global is saved for the first time. */
 {
     updatedAt: string | null;
@@ -564,14 +594,12 @@ type InferGlobal<T extends GlobalConfig, C extends Config = Config> = Simplify<
 } ? {
     status: 'draft' | 'published';
 } : unknown) & FieldsValue<T['fields'], C>>;
-type CollectionSlug<C extends Config> = NonNullable<C['collections']>[number]['slug'] | 'users' | 'media' | ApiKeysOf<C>['slug'];
+type CollectionSlug<C extends Config> = NonNullable<C['collections']>[number]['slug'] | 'users' | 'media' | ApiKeysOf<C>['slug'] | PluginCollections<C>['slug'];
 type GlobalSlug<C extends Config> = NonNullable<C['globals']>[number]['slug'];
 /** Document type of a collection, e.g. `CollectionDocument<typeof config, 'posts'>`. */
 type CollectionDocument<C extends Config, S extends CollectionSlug<C>> = S extends 'media' ? MediaDocument : InferCollection<CollectionBySlug<C, S>, C>;
 /** Data type of a global, e.g. `GlobalDocument<typeof config, 'site'>`. */
-type GlobalDocument<C extends Config, S extends GlobalSlug<C>> = InferGlobal<Extract<NonNullable<C['globals']>[number], {
-    readonly slug: S;
-}>, C>;
+type GlobalDocument<C extends Config, S extends GlobalSlug<C>> = InferGlobal<GlobalBySlug<C, S>, C>;
 type InputValue<F extends Field> = F extends {
     readonly type: 'relationship';
 } ? F extends {
@@ -630,11 +658,7 @@ type CreateInput<C extends Config, S extends CollectionSlug<C>> = Simplify<Field
 /** Data accepted by `update`: any subset of `CreateInput`. */
 type UpdateInput<C extends Config, S extends CollectionSlug<C>> = Partial<CreateInput<C, S>>;
 /** Data accepted by `updateGlobal`. */
-type GlobalInput<C extends Config, S extends GlobalSlug<C>> = Partial<Simplify<FieldsInput<Extract<NonNullable<C['globals']>[number], {
-    readonly slug: S;
-}>['fields']> & StatusInput<Extract<NonNullable<C['globals']>[number], {
-    readonly slug: S;
-}>>>>;
+type GlobalInput<C extends Config, S extends GlobalSlug<C>> = Partial<Simplify<FieldsInput<GlobalBySlug<C, S>['fields']> & StatusInput<GlobalBySlug<C, S>>>>;
 
 interface StoredFile {
     readonly body: Uint8Array;
@@ -690,6 +714,13 @@ type Create<C extends Config, S> = string extends CollectionSlug<C> ? Data$2 : C
 type Update<C extends Config, S> = string extends CollectionSlug<C> ? Data$2 : UpdateInput<C, S & CollectionSlug<C>>;
 type GDoc<C extends Config, S> = string extends GlobalSlug<C> ? Data$2 : GlobalDocument<C, S & GlobalSlug<C>>;
 type GInput<C extends Config, S> = string extends GlobalSlug<C> ? Data$2 : GlobalInput<C, S & GlobalSlug<C>>;
+/** A collection slug of the config `C` (any string when the config isn't a literal). */
+type SlugOf<C extends Config> = Slug<C>;
+/**
+ * A document of collection `S` as the Local API returns it, e.g. for helpers that take an
+ * `EasyCMS<C>`: inferred from a literal config, loose otherwise.
+ */
+type DocumentOf<C extends Config, S> = Doc<C, S>;
 interface AccessOptions {
     /**
      * The Local API trusts its caller and skips access rules by default.
@@ -1519,6 +1550,38 @@ interface Endpoint {
 }
 /** Receives the config and returns a modified copy. Runs before validation. */
 type Plugin = (config: Config) => MaybePromise<Config>;
+/** Holds a plugin's `PluginTypes` at the type level only: nothing is stored at runtime. */
+declare const PLUGIN_TYPES: unique symbol;
+/**
+ * What a plugin adds, for the document types inferred from the config: fields on collections
+ * and globals (by slug), and whole collections. Field types are written like config fields,
+ * e.g. `{ fields: { posts: readonly [{ readonly name: 'meta'; readonly type: 'group'; … }] } }`.
+ */
+interface PluginTypes {
+    readonly fields?: {
+        readonly [collection: string]: readonly Field[];
+    };
+    readonly globalFields?: {
+        readonly [global: string]: readonly Field[];
+    };
+    readonly collections?: readonly CollectionConfig[];
+}
+/** A plugin that tells the type system what it adds (see `definePlugin`). */
+type TypedPlugin<T extends PluginTypes> = Plugin & {
+    readonly [PLUGIN_TYPES]?: T;
+};
+/**
+ * Returns the plugin unchanged, with what it adds as types, so `cms.find()` and
+ * `CollectionDocument` know the plugin's fields:
+ *
+ * ```ts
+ * export const colorPlugin = (options: { collections: readonly string[] }) =>
+ *   definePlugin<{ fields: { posts: readonly [{ readonly name: 'color'; readonly type: 'text' }] } }>(
+ *     (config) => ({ ...config, collections: … }),
+ *   )
+ * ```
+ */
+declare function definePlugin<const T extends PluginTypes = Record<never, never>>(plugin: Plugin): TypedPlugin<T>;
 interface Config {
     /** Signs sessions. At least 32 characters; read it from `process.env.EASY_CMS_SECRET`. */
     readonly secret: string;
@@ -1979,4 +2042,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 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_PASSWORD_EMAILS, 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, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, 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, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, 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_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, type DocumentOf, 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, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginTypes, 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 SlugOf, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, 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, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };

package/dist/index.js

@@ -1140,6 +1140,9 @@ var ADMIN_ICONS = [
   "camera",
   "key"
 ];
+function definePlugin(plugin) {
+  return plugin;
+}
 function defineConfig(config) {
   return config;
 }
@@ -5859,6 +5862,7 @@ export {
   createRestHandler,
   createRootEndpointHandler,
   defineConfig,
+  definePlugin,
   fillMissing,
   findConfigFile,
   generateSlugs,

package/package.json

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