@easy-cms/core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -332,6 +332,10 @@ interface GlobalHooks {
     readonly afterChange?: readonly AfterChangeHook[];
     readonly afterRead?: readonly AfterReadHook[];
 }
+interface VersionsConfig {
+    /** Versions kept per document; older ones are deleted. Default 50. */
+    readonly max?: number;
+}
 interface CollectionConfig {
     /** URL and table name. Lowercase letters, digits, `-` and `_`. */
     readonly slug: string;
@@ -344,6 +348,12 @@ interface CollectionConfig {
     readonly useAsTitle?: string;
     /** Adds a `status` field (`draft` | `published`). */
     readonly drafts?: boolean;
+    /**
+     * Keep a snapshot of every save, to view history and restore. With `drafts`, a draft saved
+     * on a published document is kept as a version and the published document stays live until
+     * it is published again.
+     */
+    readonly versions?: boolean | VersionsConfig;
     readonly access?: CollectionAccess;
     readonly hooks?: CollectionHooks;
 }
@@ -352,6 +362,8 @@ interface GlobalConfig {
     readonly label?: Label;
     readonly fields: readonly Field[];
     readonly drafts?: boolean;
+    /** Keep a snapshot of every save. See `CollectionConfig.versions`. */
+    readonly versions?: boolean | VersionsConfig;
     readonly access?: GlobalAccess;
     readonly hooks?: GlobalHooks;
 }
@@ -647,6 +659,23 @@ type GlobalInput<C extends Config, S extends GlobalSlug<C>> = Partial<Simplify<F
     readonly slug: S;
 }>>>>;
 
+declare const DEFAULT_MAX_VERSIONS = 50;
+/** One saved state of a document or global. */
+interface VersionSummary {
+    readonly id: ID;
+    /** `draft` or `published` with drafts enabled, otherwise `null`. */
+    readonly status: 'draft' | 'published' | null;
+    /** The newest version: the document's current editable state. */
+    readonly latest: boolean;
+    /** Who saved it (user id), or `null` for saves without a user (scripts, seeds). */
+    readonly author: ID | null;
+    readonly createdAt: string;
+}
+interface Version<T = Record<string, unknown>> extends VersionSummary {
+    /** The document as it was saved (hidden fields such as password hashes are never kept). */
+    readonly data: T;
+}
+
 type Data$1 = Record<string, unknown>;
 type Slug<C extends Config> = string extends CollectionSlug<C> ? string : CollectionSlug<C>;
 type GSlug<C extends Config> = string extends GlobalSlug<C> ? string : GlobalSlug<C>;
@@ -702,6 +731,7 @@ declare class EasyCMS<C extends Config = Config> {
     readonly auth: Auth;
     /** Where uploaded files are stored. */
     readonly storage: StorageAdapter;
+    private readonly versions;
     constructor(config: ResolvedConfig, db: Database, logger?: Logger, storage?: StorageAdapter);
     find<S extends Slug<C>>(collection: S, options?: FindOptions): Promise<PaginatedDocs<Doc<C, S>>>;
     findById<S extends Slug<C>>(collection: S, id: ID, options?: ReadOptions): Promise<Doc<C, S> | null>;
@@ -721,9 +751,47 @@ 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>>;
+    /**
+     * 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;
+     * this is how to unpublish it.
+     */
+    unpublish<S extends Slug<C>>(collection: S, id: ID, options?: DepthOptions): Promise<Doc<C, S>>;
+    /** Throws away the unpublished draft of a published document, going back to what is live. */
+    discardDraft<S extends Slug<C>>(collection: S, id: ID, options?: DepthOptions): Promise<Doc<C, S>>;
+    /** Saved versions of a document, newest first. Needs update access to the document. */
+    findVersions<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions & {
+        limit?: number;
+        page?: number;
+    }): Promise<PaginatedDocs<VersionSummary>>;
+    /** One saved version with the document as it was then. */
+    findVersion<S extends Slug<C>>(collection: S, id: ID, versionId: ID, options?: DepthOptions): Promise<Version<Doc<C, S>> | null>;
+    /**
+     * Makes an old version the current content, as a new version. With drafts it is restored as
+     * a draft (publish it to put it live); access, hooks and validation run as for `update`.
+     */
+    restoreVersion<S extends Slug<C>>(collection: S, id: ID, versionId: ID, options?: DepthOptions): Promise<Doc<C, S>>;
+    private versionTarget;
+    private updateDocument;
     delete<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions): Promise<Doc<C, S>>;
     findGlobal<S extends GSlug<C>>(slug: S, options?: ReadOptions): Promise<GDoc<C, S>>;
     updateGlobal<S extends GSlug<C>>(slug: S, data: GInput<C, S>, options?: DepthOptions): Promise<GDoc<C, S>>;
+    /** Takes a global off the site (`status: 'draft'`). See `unpublish`. */
+    unpublishGlobal<S extends GSlug<C>>(slug: S, options?: DepthOptions): Promise<GDoc<C, S>>;
+    /** Throws away the unpublished draft of a published global. */
+    discardGlobalDraft<S extends GSlug<C>>(slug: S, options?: DepthOptions): Promise<GDoc<C, S>>;
+    /** Saved versions of a global, newest first. Needs update access. */
+    findGlobalVersions<S extends GSlug<C>>(slug: S, options?: AccessOptions & {
+        limit?: number;
+        page?: number;
+    }): Promise<PaginatedDocs<VersionSummary>>;
+    findGlobalVersion<S extends GSlug<C>>(slug: S, versionId: ID, options?: DepthOptions): Promise<Version<GDoc<C, S>> | null>;
+    /** Makes an old version of a global current (as a draft when the global has drafts). */
+    restoreGlobalVersion<S extends GSlug<C>>(slug: S, versionId: ID, options?: DepthOptions): Promise<GDoc<C, S>>;
+    private globalVersionTarget;
+    /** The global's pending draft when it has one (see `withDrafts`), otherwise `saved`. */
+    private globalDraft;
+    private saveGlobal;
     /**
      * What `user` may do with one document. Resolves `where`-style access
      * against the document, so the admin UI can hide actions precisely.
@@ -746,6 +814,12 @@ declare class EasyCMS<C extends Config = Config> {
     private output;
     /** Creates a document: access, input filtering, hooks, validation, then afterChange. */
     private createDocument;
+    /** Drafts are kept as versions (instead of unpublishing) when both are enabled. */
+    private separateDrafts;
+    /** Replaces published documents that have a newer draft with that draft. */
+    private withDrafts;
+    /** Records a version after a save, when the collection or global keeps versions. */
+    private saveVersion;
     private hookArgs;
     /**
      * Runs hooks that may replace a value, passed as `data` (before hooks) or `doc` (afterRead).
@@ -1001,6 +1075,7 @@ interface AdminCollection {
     };
     useAsTitle?: string;
     drafts: boolean;
+    versions: boolean;
     fields: AdminField[];
     permissions: {
         read: boolean;
@@ -1013,6 +1088,7 @@ interface AdminGlobal {
     slug: string;
     label?: Label;
     drafts: boolean;
+    versions: boolean;
     fields: AdminField[];
     permissions: {
         read: boolean;
@@ -1053,4 +1129,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 { type Access, type AccessArgs, type AccessOptions, type AdminCollection, type AdminConfig, type AdminField, type AdminGlobal, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type BooleanField, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CollectionAccess, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailField, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, 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 LoadConfigOptions, type LocalStorageOptions, 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, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, 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 Where, type WhereOperators, anyone, applyDefaults, consoleLogger, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveConfig, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };
+export { type Access, type AccessArgs, type AccessOptions, type AdminCollection, type AdminConfig, type AdminField, type AdminGlobal, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type BooleanField, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CollectionAccess, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionSlug, type Config, ConfigError, type ConfigIssue, 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 DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailField, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, 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 LoadConfigOptions, type LocalStorageOptions, 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, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, 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, type Where, type WhereOperators, anyone, applyDefaults, consoleLogger, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveConfig, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };

package/dist/index.js

@@ -160,7 +160,12 @@ var USERS = "users";
 var MEDIA = "media";
 var SESSIONS = "sessions";
 var LOGIN_ATTEMPTS = "login-attempts";
-var INTERNAL_COLLECTIONS = /* @__PURE__ */ new Set([SESSIONS, LOGIN_ATTEMPTS]);
+var VERSIONS = "document-versions";
+var INTERNAL_COLLECTIONS = /* @__PURE__ */ new Set([
+  SESSIONS,
+  LOGIN_ATTEMPTS,
+  VERSIONS
+]);
 var DEFAULT_ROLES = ["admin", "editor"];
 var adminOrSelf = ({ user }) => {
   if (!user) return false;
@@ -325,6 +330,21 @@ var internalCollections = [
     fields: [{ name: "key", type: "text", required: true, index: true }]
   }
 ];
+var versionsCollection = {
+  slug: VERSIONS,
+  access: { read: nobody, create: nobody, update: nobody, delete: nobody },
+  fields: [
+    // Collection slug, or `global:<slug>`.
+    { name: "parent", type: "text", required: true, index: true },
+    // Document id; 0 for globals.
+    { name: "doc", type: "number", required: true, index: true },
+    { name: "status", type: "text" },
+    // The newest version of the document: its current editable state.
+    { name: "latest", type: "boolean", index: true },
+    { name: "author", type: "number" },
+    { name: "snapshot", type: "json", required: true }
+  ]
+};
 
 // src/auth/password.ts
 import { randomBytes, scrypt, timingSafeEqual } from "crypto";
@@ -847,6 +867,7 @@ var RESERVED_SLUGS = /* @__PURE__ */ new Set([
   "globals",
   "sessions",
   "login-attempts",
+  "document-versions",
   "migrations",
   "access"
 ]);
@@ -1002,6 +1023,15 @@ function validateContainer(container, path, collectionSlugs, add) {
     add(`${path}.fields`, "must be an array");
     return;
   }
+  const versions = container.versions;
+  if (versions !== void 0 && typeof versions !== "boolean") {
+    const max = typeof versions === "object" && versions !== null ? versions.max : void 0;
+    if (typeof versions !== "object" || versions === null) {
+      add(`${path}.versions`, "must be true, false or { max }");
+    } else if (max !== void 0 && (!Number.isInteger(max) || max < 1)) {
+      add(`${path}.versions.max`, "must be a positive integer");
+    }
+  }
   const reserved = new Set(SYSTEM_FIELD_NAMES);
   if (container.drafts) reserved.add("status");
   validateFields2(container.fields, `${path}.fields`, reserved, collectionSlugs, add);
@@ -1161,12 +1191,19 @@ async function resolveConfig(input) {
       lockWindow: config.auth?.lockWindow ?? 15 * 60,
       trustedOrigins: config.auth?.trustedOrigins ?? []
     },
-    collections: [...config.collections ?? [], ...internalCollections],
+    collections: [
+      ...config.collections ?? [],
+      ...internalCollections,
+      ...usesVersions(config) ? [versionsCollection] : []
+    ],
     globals: config.globals ?? []
   };
   resolved.add(result);
   return result;
 }
+function usesVersions(config) {
+  return [...config.collections ?? [], ...config.globals ?? []].some((c) => c.versions);
+}
 
 // src/load-config.ts
 var CONFIG_FILE_NAMES = [
@@ -1429,6 +1466,137 @@ function localStorage(options = {}) {
   };
 }
 
+// src/versions.ts
+var DEFAULT_MAX_VERSIONS = 50;
+function versionLimit(config) {
+  const versions = config.versions;
+  if (!versions) return void 0;
+  return versions === true ? DEFAULT_MAX_VERSIONS : versions.max ?? DEFAULT_MAX_VERSIONS;
+}
+var collectionParent = (slug) => slug;
+var globalParent = (slug) => `global:${slug}`;
+function snapshotOf(fields, doc) {
+  const hidden = new Set(fields.filter((f) => f.hidden).map((f) => f.name));
+  const snapshot = {};
+  for (const [key2, value] of Object.entries(doc)) {
+    if (key2 === "id" || key2 === "createdAt" || key2 === "updatedAt" || hidden.has(key2)) continue;
+    snapshot[key2] = value;
+  }
+  return snapshot;
+}
+var toSummary = (row) => ({
+  id: row.id,
+  status: row.status ?? null,
+  latest: row.latest === true,
+  author: row.author ?? null,
+  createdAt: String(row.createdAt)
+});
+var VersionStore = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  /** Saves a new latest version and deletes the oldest beyond `max`. */
+  async save(args) {
+    const { parent, doc } = args;
+    const previous = await this.db.find({
+      collection: VERSIONS,
+      where: { and: [...this.of(parent, doc), { latest: { equals: true } }] },
+      sort: [],
+      limit: 0,
+      page: 1
+    });
+    for (const row of previous.docs) {
+      await this.db.update({ collection: VERSIONS, id: row.id, data: { ...row, latest: false } });
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const created = await this.db.create({
+      collection: VERSIONS,
+      data: {
+        parent,
+        doc,
+        status: args.status,
+        latest: true,
+        author: args.author,
+        snapshot: args.snapshot,
+        createdAt: now,
+        updatedAt: now
+      }
+    });
+    await this.prune(parent, doc, args.max);
+    return toSummary(created);
+  }
+  /** The latest version of each document, keyed by document id. */
+  async latest(parent, docs) {
+    const result = /* @__PURE__ */ new Map();
+    if (docs.length === 0) return result;
+    const rows = await this.db.find({
+      collection: VERSIONS,
+      where: {
+        and: [
+          { parent: { equals: parent } },
+          { doc: { in: [...docs] } },
+          { latest: { equals: true } }
+        ]
+      },
+      sort: [],
+      limit: 0,
+      page: 1
+    });
+    for (const row of rows.docs) result.set(String(row.doc), this.toVersion(row));
+    return result;
+  }
+  async list(parent, doc, limit, page) {
+    const found = await this.db.find({
+      collection: VERSIONS,
+      where: { and: this.of(parent, doc) },
+      sort: ["-id"],
+      limit,
+      page
+    });
+    return { ...found, docs: found.docs.map(toSummary) };
+  }
+  async get(parent, doc, id) {
+    const found = await this.db.find({
+      collection: VERSIONS,
+      where: { and: [...this.of(parent, doc), { id: { equals: id } }] },
+      sort: [],
+      limit: 1,
+      page: 1
+    });
+    const row = found.docs[0];
+    return row ? this.toVersion(row) : null;
+  }
+  async deleteAll(parent, doc) {
+    const rows = await this.db.find({
+      collection: VERSIONS,
+      where: { and: this.of(parent, doc) },
+      sort: [],
+      limit: 0,
+      page: 1
+    });
+    for (const row of rows.docs) await this.db.delete({ collection: VERSIONS, id: row.id });
+  }
+  async prune(parent, doc, max) {
+    const rows = await this.db.find({
+      collection: VERSIONS,
+      where: { and: this.of(parent, doc) },
+      sort: ["-id"],
+      limit: 0,
+      page: 1
+    });
+    for (const row of rows.docs.slice(max)) {
+      await this.db.delete({ collection: VERSIONS, id: row.id });
+    }
+  }
+  of(parent, doc) {
+    return [{ parent: { equals: parent } }, { doc: { equals: doc } }];
+  }
+  toVersion(row) {
+    return { ...toSummary(row), data: row.snapshot ?? {} };
+  }
+};
+
 // src/local-api.ts
 async function createEasyCMS(config, options = {}) {
   const resolved2 = await resolveConfig(config);
@@ -1453,11 +1621,13 @@ var EasyCMS = class {
   auth;
   /** Where uploaded files are stored. */
   storage;
+  versions;
   constructor(config, db, logger = consoleLogger, storage = localStorage({ dir: config.upload.dir })) {
     this.config = config;
     this.db = db;
     this.logger = logger;
     this.storage = storage;
+    this.versions = new VersionStore(db);
     this.auth = new Auth(this);
   }
   async find(collection2, options = {}) {
@@ -1475,7 +1645,8 @@ var EasyCMS = class {
     );
     const sort = options.sort === void 0 ? ["-createdAt"] : [options.sort].flat();
     const result = await this.db.find({ collection: collection2, where, sort, limit, page });
-    const docs = await this.output(config, result.docs, guard, options);
+    const found = options.draft ? await this.withDrafts(config, result.docs) : result.docs;
+    const docs = await this.output(config, found, guard, options);
     return { ...result, docs };
   }
   async findById(collection2, id, options = {}) {
@@ -1492,7 +1663,8 @@ var EasyCMS = class {
       page: 1
     })).docs[0] : await this.db.findById({ collection: collection2, id: parsed });
     if (!doc) return null;
-    const [out] = await this.output(config, [doc], guard, options);
+    const [current] = options.draft ? await this.withDrafts(config, [doc]) : [doc];
+    const [out] = await this.output(config, [current], guard, options);
     return out ?? null;
   }
   async count(collection2, options = {}) {
@@ -1577,27 +1749,113 @@ var EasyCMS = class {
     return `${this.config.serverURL?.replace(/\/+$/, "") ?? ""}${this.config.routes.api}/media/file/${encodeURIComponent(key2)}`;
   }
   async update(collection2, id, data, options = {}) {
+    return await this.updateDocument(collection2, id, asObject(data, collection2), options);
+  }
+  /**
+   * 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;
+   * this is how to unpublish it.
+   */
+  async unpublish(collection2, id, options = {}) {
+    const config = this.collection(collection2);
+    if (!config.drafts) throw new QueryError(`"${collection2}" has no drafts`);
+    return await this.updateDocument(
+      collection2,
+      id,
+      { status: "draft" },
+      options,
+      "unpublish"
+    );
+  }
+  /** Throws away the unpublished draft of a published document, going back to what is live. */
+  async discardDraft(collection2, id, options = {}) {
+    const config = this.collection(collection2);
+    const guard = guardOf(options);
+    const parsed = parseId(id);
+    const existing = parsed === void 0 ? null : await this.db.findById({ collection: collection2, id: parsed });
+    if (!existing || parsed === void 0) throw new NotFoundError(collection2, id);
+    await this.checkDocumentAccess(config, "update", guard, parsed, void 0);
+    const [current] = await this.withDrafts(config, [existing]);
+    if (current !== existing) {
+      await this.saveVersion(config, collectionParent(collection2), parsed, existing, guard);
+    }
+    const [out] = await this.output(config, [existing], guard, { ...options, draft: true });
+    return out;
+  }
+  /** Saved versions of a document, newest first. Needs update access to the document. */
+  async findVersions(collection2, id, options = {}) {
+    const { config, parsed } = await this.versionTarget(collection2, id, options);
+    return this.versions.list(
+      collectionParent(config.slug),
+      parsed,
+      options.limit ?? 20,
+      options.page ?? 1
+    );
+  }
+  /** One saved version with the document as it was then. */
+  async findVersion(collection2, id, versionId, options = {}) {
+    const { config, parsed, existing } = await this.versionTarget(collection2, id, options);
+    const version = await this.versions.get(collectionParent(config.slug), parsed, versionId);
+    if (!version) return null;
+    const doc = {
+      ...version.data,
+      id: parsed,
+      createdAt: existing.createdAt,
+      updatedAt: version.createdAt
+    };
+    const [out] = await this.output(config, [doc], guardOf(options), {
+      ...options,
+      draft: true
+    });
+    return { ...version, data: out };
+  }
+  /**
+   * Makes an old version the current content, as a new version. With drafts it is restored as
+   * a draft (publish it to put it live); access, hooks and validation run as for `update`.
+   */
+  async restoreVersion(collection2, id, versionId, options = {}) {
+    const { config, parsed } = await this.versionTarget(collection2, id, options);
+    const version = await this.versions.get(collectionParent(config.slug), parsed, versionId);
+    if (!version) throw new NotFoundError(`${collection2} version`, versionId);
+    const { status: _status, ...data } = version.data;
+    return await this.updateDocument(
+      collection2,
+      parsed,
+      config.drafts ? { ...data, status: "draft" } : data,
+      options
+    );
+  }
+  async versionTarget(collection2, id, options) {
+    const config = this.collection(collection2);
+    if (!versionLimit(config)) throw new QueryError(`"${collection2}" has no versions`);
+    const parsed = parseId(id);
+    const existing = parsed === void 0 ? null : await this.db.findById({ collection: collection2, id: parsed });
+    if (!existing || parsed === void 0) throw new NotFoundError(collection2, id);
+    await this.checkDocumentAccess(config, "update", guardOf(options), parsed, void 0);
+    return { config, parsed, existing };
+  }
+  async updateDocument(collection2, id, raw, options, mode = "save") {
     const config = this.collection(collection2);
     const guard = guardOf(options);
-    const raw = asObject(data, collection2);
     const parsed = parseId(id);
     const existing = parsed === void 0 ? null : await this.db.findById({ collection: collection2, id: parsed });
     if (!existing || parsed === void 0) throw new NotFoundError(collection2, id);
     await this.checkDocumentAccess(config, "update", guard, parsed, raw);
+    const [current] = await this.withDrafts(config, [existing]);
     const { input, password } = splitPassword(config, raw);
     const filtered = await filterInput(
       config.fields,
       input,
       this.fieldChecker("update", guard, parsed, input)
     );
-    let merged = mergeForUpdate(config.fields, existing, filtered);
+    let merged = mergeForUpdate(config.fields, current, filtered);
     if (config.drafts)
-      merged.status = Object.hasOwn(filtered, "status") ? filtered.status : existing.status;
+      merged.status = Object.hasOwn(filtered, "status") ? filtered.status : current.status;
     const base = this.hookArgs(config, guard);
     merged = await this.transform(
       config.hooks?.beforeValidate,
       "data",
-      { ...base, operation: "update", originalDoc: existing },
+      { ...base, operation: "update", originalDoc: current },
       merged
     );
     let prepared = await this.prepare(
@@ -1609,21 +1867,43 @@ var EasyCMS = class {
     prepared = await this.transform(
       config.hooks?.beforeChange,
       "data",
-      { ...base, operation: "update", originalDoc: existing },
+      { ...base, operation: "update", originalDoc: current },
       prepared
     );
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (mode === "save" && this.separateDrafts(config) && existing.status === "published" && prepared.status === "draft") {
+      if (password !== void 0) {
+        throw new ValidationError(collection2, [
+          { field: "password", message: "cannot be changed in a draft; publish instead" }
+        ]);
+      }
+      const draft = { ...prepared, id: parsed, createdAt: existing.createdAt, updatedAt: now };
+      await this.saveVersion(config, collectionParent(collection2), parsed, draft, guard);
+      await this.notify(config.hooks?.afterChange, "afterChange", config.slug, {
+        ...base,
+        doc: draft,
+        previousDoc: current,
+        operation: "update"
+      });
+      const [out2] = await this.output(config, [draft], guard, {
+        ...options,
+        draft: true
+      });
+      return out2;
+    }
     if (config.slug === USERS) await this.guardLastAdmin(parsed, existing, prepared);
     if (password !== void 0) prepared.passwordHash = await hashPassword(password);
     const doc = await this.db.update({
       collection: collection2,
       id: parsed,
-      data: { ...prepared, createdAt: existing.createdAt, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }
+      data: { ...prepared, createdAt: existing.createdAt, updatedAt: now }
     });
+    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,
       doc,
-      previousDoc: existing,
+      previousDoc: current,
       operation: "update"
     });
     const [out] = await this.output(config, [doc], guard, { ...options, draft: true });
@@ -1642,6 +1922,7 @@ var EasyCMS = class {
     for (const hook of config.hooks?.beforeDelete ?? []) await hook({ ...base, id: parsed });
     if (config.slug === USERS) await this.auth.revokeSessions(parsed);
     await this.db.delete({ collection: collection2, id: parsed });
+    if (versionLimit(config)) await this.versions.deleteAll(collectionParent(collection2), parsed);
     await this.notify(config.hooks?.afterDelete, "afterDelete", config.slug, {
       ...base,
       id: parsed,
@@ -1654,7 +1935,8 @@ var EasyCMS = class {
     const config = this.global(slug);
     const guard = guardOf(options);
     await this.checkGlobalAccess(config, "read", guard);
-    const stored = await this.db.findGlobal({ slug });
+    const saved = await this.db.findGlobal({ slug });
+    const stored = saved && options.draft ? await this.globalDraft(config, saved) : saved;
     const data = fillMissing(config.fields, applyDefaults(config.fields, stored ?? {}));
     if (!stored) {
       data.updatedAt = null;
@@ -1665,37 +1947,108 @@ var EasyCMS = class {
     return doc;
   }
   async updateGlobal(slug, data, options = {}) {
+    return this.saveGlobal(slug, asObject(data, slug), options);
+  }
+  /** Takes a global off the site (`status: 'draft'`). See `unpublish`. */
+  async unpublishGlobal(slug, options = {}) {
+    if (!this.global(slug).drafts) throw new QueryError(`"${slug}" has no drafts`);
+    return this.saveGlobal(slug, { status: "draft" }, options, "unpublish");
+  }
+  /** Throws away the unpublished draft of a published global. */
+  async discardGlobalDraft(slug, options = {}) {
+    const config = this.global(slug);
+    const guard = guardOf(options);
+    await this.checkGlobalAccess(config, "update", guard);
+    const saved = await this.db.findGlobal({ slug });
+    if (saved && await this.globalDraft(config, saved) !== saved) {
+      await this.saveVersion(config, globalParent(slug), 0, saved, guard);
+    }
+    return this.findGlobal(slug, { ...options, draft: true });
+  }
+  /** Saved versions of a global, newest first. Needs update access. */
+  async findGlobalVersions(slug, options = {}) {
+    await this.globalVersionTarget(slug, options);
+    return this.versions.list(globalParent(slug), 0, options.limit ?? 20, options.page ?? 1);
+  }
+  async findGlobalVersion(slug, versionId, options = {}) {
+    const config = await this.globalVersionTarget(slug, options);
+    const version = await this.versions.get(globalParent(slug), 0, versionId);
+    if (!version) return null;
+    const data = fillMissing(config.fields, applyDefaults(config.fields, version.data));
+    const [out] = await this.output(config, [{ ...data, id: 0 }], guardOf(options), {
+      ...options,
+      draft: true
+    });
+    const { id: _id, ...doc } = out;
+    return { ...version, data: { ...doc, updatedAt: version.createdAt } };
+  }
+  /** Makes an old version of a global current (as a draft when the global has drafts). */
+  async restoreGlobalVersion(slug, versionId, options = {}) {
+    const config = await this.globalVersionTarget(slug, options);
+    const version = await this.versions.get(globalParent(slug), 0, versionId);
+    if (!version) throw new NotFoundError(`${slug} version`, versionId);
+    const { status: _status, ...data } = version.data;
+    return this.saveGlobal(
+      slug,
+      config.drafts ? { ...data, status: "draft" } : data,
+      options
+    );
+  }
+  async globalVersionTarget(slug, options) {
+    const config = this.global(slug);
+    if (!versionLimit(config)) throw new QueryError(`"${slug}" has no versions`);
+    await this.checkGlobalAccess(config, "update", guardOf(options));
+    return config;
+  }
+  /** The global's pending draft when it has one (see `withDrafts`), otherwise `saved`. */
+  async globalDraft(config, saved) {
+    if (!this.separateDrafts(config) || saved.status !== "published") return saved;
+    const version = (await this.versions.latest(globalParent(config.slug), [0])).get("0");
+    if (version?.status !== "draft") return saved;
+    return { ...version.data, updatedAt: version.createdAt, status: "draft" };
+  }
+  async saveGlobal(slug, raw, options, mode = "save") {
     const config = this.global(slug);
     const guard = guardOf(options);
     await this.checkGlobalAccess(config, "update", guard);
-    const raw = asObject(data, slug);
     const input = await filterInput(
       config.fields,
       raw,
       this.fieldChecker("update", guard, void 0, raw)
     );
     const existing = await this.db.findGlobal({ slug }) ?? {};
+    const current = await this.globalDraft(config, existing);
     const merged = generateSlugs(
       config.fields,
-      applyDefaults(config.fields, mergeForUpdate(config.fields, existing, input))
+      applyDefaults(config.fields, mergeForUpdate(config.fields, current, input))
     );
-    if (config.drafts) merged.status = input.status ?? existing.status ?? "draft";
+    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);
     prepared = await this.transform(
       config.hooks?.beforeChange,
       "data",
-      { ...base, operation: "update", originalDoc: existing },
+      { ...base, operation: "update", originalDoc: current },
       prepared
     );
-    const doc = await this.db.updateGlobal({
-      slug,
-      data: { ...prepared, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }
-    });
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (mode === "save" && this.separateDrafts(config) && existing.status === "published" && prepared.status === "draft") {
+      const draft = { ...prepared, updatedAt: now };
+      await this.saveVersion(config, globalParent(slug), 0, draft, guard);
+      await this.notify(config.hooks?.afterChange, "afterChange", slug, {
+        ...base,
+        doc: draft,
+        previousDoc: current,
+        operation: "update"
+      });
+      return this.findGlobal(slug, { ...options, draft: true });
+    }
+    const doc = await this.db.updateGlobal({ slug, data: { ...prepared, updatedAt: now } });
+    await this.saveVersion(config, globalParent(slug), 0, doc, guard);
     await this.notify(config.hooks?.afterChange, "afterChange", slug, {
       ...base,
       doc,
-      previousDoc: existing,
+      previousDoc: current,
       operation: "update"
     });
     return this.findGlobal(slug, { ...options, draft: true });
@@ -1798,7 +2151,8 @@ var EasyCMS = class {
         limit: 0,
         page: 1
       });
-      return Promise.all(found.docs.map((d) => finish(target, d)));
+      const docs2 = options.draft ? await this.withDrafts(target, found.docs) : found.docs;
+      return Promise.all(docs2.map((d) => finish(target, d)));
     };
     const depth = Math.max(0, Math.min(MAX_DEPTH, Math.trunc(options.depth ?? DEFAULT_DEPTH)));
     const populated = await populate(load, this.config.collections, config.fields, docs, depth);
@@ -1849,6 +2203,7 @@ var EasyCMS = class {
       collection: collection2,
       data: { ...prepared, createdAt: now, updatedAt: now }
     });
+    await this.saveVersion(config, collectionParent(collection2), doc.id, doc, guard);
     await this.notify(config.hooks?.afterChange, "afterChange", collection2, {
       ...base,
       doc,
@@ -1857,6 +2212,33 @@ var EasyCMS = class {
     const [out] = await this.output(config, [doc], hookGuard ?? guard, { ...options, draft: true });
     return out;
   }
+  /** Drafts are kept as versions (instead of unpublishing) when both are enabled. */
+  separateDrafts(config) {
+    return config.drafts === true && versionLimit(config) !== void 0;
+  }
+  /** Replaces published documents that have a newer draft with that draft. */
+  async withDrafts(config, docs) {
+    if (!this.separateDrafts(config)) return docs;
+    const published = docs.filter((d) => d.status === "published").map((d) => d.id);
+    const latest = await this.versions.latest(collectionParent(config.slug), published);
+    return docs.map((doc) => {
+      const version = latest.get(String(doc.id));
+      return version && doc.status === "published" && version.status === "draft" ? draftOf(doc, version) : doc;
+    });
+  }
+  /** Records a version after a save, when the collection or global keeps versions. */
+  async saveVersion(config, parent, id, doc, guard) {
+    const max = versionLimit(config);
+    if (max === void 0) return;
+    await this.versions.save({
+      parent,
+      doc: id,
+      status: config.drafts ? doc.status ?? "draft" : null,
+      snapshot: snapshotOf(config.fields, doc),
+      author: guard.user?.id ?? null,
+      max
+    });
+  }
   hookArgs(config, guard) {
     return { user: guard.user, cms: this, slug: config.slug };
   }
@@ -2014,6 +2396,15 @@ var EasyCMS = class {
     return errors;
   }
 };
+function draftOf(doc, version) {
+  return {
+    ...version.data,
+    id: doc.id,
+    createdAt: doc.createdAt,
+    updatedAt: version.createdAt,
+    status: "draft"
+  };
+}
 function draftWhere(config, draft, where) {
   if (!config.drafts || draft) return where;
   return andWhere(where, { status: { equals: "published" } });
@@ -2107,6 +2498,7 @@ async function collection(config, user) {
   const result = {
     slug: config.slug,
     drafts: config.drafts === true,
+    versions: Boolean(config.versions),
     fields: await serializeFields(config.fields, new FieldAccessChecker("update", { user })),
     permissions: {
       read: await allowed(config.access?.read, user),
@@ -2123,6 +2515,7 @@ async function global(config, user) {
   const result = {
     slug: config.slug,
     drafts: config.drafts === true,
+    versions: Boolean(config.versions),
     fields: await serializeFields(config.fields, new FieldAccessChecker("update", { user })),
     permissions: {
       read: await allowed(config.access?.read, user),
@@ -2369,9 +2762,10 @@ async function route(cms, ctx, method, segments, options) {
     throw new HttpError("Not found", 404);
   }
   if (first === "globals") {
-    if (!second || third !== void 0) throw new HttpError("Not found", 404);
+    if (!second) throw new HttpError("Not found", 404);
     if (!cms.config.globals.some((g) => g.slug === second))
       throw new HttpError(`Unknown global "${second}"`, 404);
+    if (third !== void 0) return globalAction(cms, ctx, method, second, segments.slice(2));
     if (method === "GET")
       return { body: await cms.findGlobal(second, { ...access, ...parseDepth(ctx.url), draft }) };
     if (method === "POST") {
@@ -2395,7 +2789,9 @@ async function route(cms, ctx, method, segments, options) {
   if (INTERNAL_COLLECTIONS.has(collection2) || !cms.config.collections.some((c) => c.slug === collection2)) {
     throw new HttpError(`Unknown collection "${collection2}"`, 404);
   }
-  if (third !== void 0) throw new HttpError("Not found", 404);
+  if (second !== void 0 && third !== void 0) {
+    return documentAction(cms, ctx, method, collection2, second, segments.slice(2));
+  }
   if (second === void 0) {
     if (method === "GET") {
       const query = parseListQuery(ctx.url);
@@ -2429,6 +2825,64 @@ async function route(cms, ctx, method, segments, options) {
   }
   throw methodNotAllowed(ctx, "GET, PATCH, DELETE");
 }
+async function documentAction(cms, ctx, method, collection2, id, path) {
+  const access = { overrideAccess: false, user: ctx.user };
+  const depth = parseDepth(ctx.url);
+  const [action, versionId, extra] = path;
+  if (action === "versions" && versionId === void 0) {
+    if (method !== "GET") throw methodNotAllowed(ctx, "GET");
+    return { body: await cms.findVersions(collection2, id, { ...access, ...parsePage(ctx.url) }) };
+  }
+  if (action === "versions" && versionId !== void 0 && extra === void 0) {
+    if (method !== "GET") throw methodNotAllowed(ctx, "GET");
+    const version = await cms.findVersion(collection2, id, versionId, { ...access, ...depth });
+    if (!version) throw new NotFoundError(`${collection2} version`, versionId);
+    return { body: version };
+  }
+  if (action === "versions" && versionId !== void 0 && extra === "restore" && path.length === 3) {
+    if (method !== "POST") throw methodNotAllowed(ctx, "POST");
+    return { body: await cms.restoreVersion(collection2, id, versionId, { ...access, ...depth }) };
+  }
+  if (path.length === 1 && (action === "unpublish" || action === "discard-draft")) {
+    if (method !== "POST") throw methodNotAllowed(ctx, "POST");
+    const options = { ...access, ...depth };
+    return {
+      body: action === "unpublish" ? await cms.unpublish(collection2, id, options) : await cms.discardDraft(collection2, id, options)
+    };
+  }
+  throw new HttpError("Not found", 404);
+}
+async function globalAction(cms, ctx, method, slug, path) {
+  const access = { overrideAccess: false, user: ctx.user };
+  const depth = parseDepth(ctx.url);
+  const [action, versionId, extra] = path;
+  if (action === "versions" && versionId === void 0) {
+    if (method !== "GET") throw methodNotAllowed(ctx, "GET");
+    return { body: await cms.findGlobalVersions(slug, { ...access, ...parsePage(ctx.url) }) };
+  }
+  if (action === "versions" && versionId !== void 0 && extra === void 0) {
+    if (method !== "GET") throw methodNotAllowed(ctx, "GET");
+    const version = await cms.findGlobalVersion(slug, versionId, { ...access, ...depth });
+    if (!version) throw new NotFoundError(`${slug} version`, versionId);
+    return { body: version };
+  }
+  if (action === "versions" && versionId !== void 0 && extra === "restore" && path.length === 3) {
+    if (method !== "POST") throw methodNotAllowed(ctx, "POST");
+    return { body: await cms.restoreGlobalVersion(slug, versionId, { ...access, ...depth }) };
+  }
+  if (path.length === 1 && (action === "unpublish" || action === "discard-draft")) {
+    if (method !== "POST") throw methodNotAllowed(ctx, "POST");
+    const options = { ...access, ...depth };
+    return {
+      body: action === "unpublish" ? await cms.unpublishGlobal(slug, options) : await cms.discardGlobalDraft(slug, options)
+    };
+  }
+  throw new HttpError("Not found", 404);
+}
+function parsePage(url) {
+  const { page, limit } = parseListQuery(url);
+  return { page, limit };
+}
 function methodNotAllowed(ctx, allow) {
   ctx.headers.set("allow", allow);
   return new HttpError("Method not allowed", 405);
@@ -2734,6 +3188,7 @@ export {
   DEFAULT_API_PATH,
   DEFAULT_DEPTH,
   DEFAULT_MAX_FILE_SIZE,
+  DEFAULT_MAX_VERSIONS,
   DEFAULT_TOKEN_EXPIRATION,
   EXTENSIONS,
   EasyCMS,

package/package.json

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