@momentumcms/core 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@momentumcms/core",
-	"version": "0.4.1",
+	"version": "0.5.1",
 	"description": "Core collection config, fields, hooks, and access control for Momentum CMS",
 	"license": "MIT",
 	"author": "Momentum CMS Contributors",

package/src/generators/generator.cjs

@@ -711,7 +711,9 @@ function generateAdminConfig(config, typesRelPath) {
   }
   lines.push(`import type { ${typeImports.join(", ")} } from '${typesRelPath}';`);
   for (const plugin of pluginsWithAdminRoutes) {
-    const imp = plugin.browserImports.adminRoutes;
+    const imp = plugin.browserImports?.adminRoutes;
+    if (!imp)
+      continue;
     lines.push(`import { ${imp.exportName} } from '${imp.path}';`);
   }
   lines.push("");
@@ -744,9 +746,11 @@ ${globalItems},
     }
   }
   if (pluginsWithAdminRoutes.length > 0) {
-    const pluginItems = pluginsWithAdminRoutes.map((p) => {
-      const imp = p.browserImports.adminRoutes;
-      return `		{ name: ${JSON.stringify(p.name)}, adminRoutes: ${imp.exportName} }`;
+    const pluginItems = pluginsWithAdminRoutes.flatMap((p) => {
+      const imp = p.browserImports?.adminRoutes;
+      if (!imp)
+        return [];
+      return [`		{ name: ${JSON.stringify(p.name)}, adminRoutes: ${imp.exportName} }`];
     }).join(",\n");
     lines.push(`	plugins: [
 ${pluginItems},

package/src/generators/generator.js

@@ -680,7 +680,9 @@ function generateAdminConfig(config, typesRelPath) {
   }
   lines.push(`import type { ${typeImports.join(", ")} } from '${typesRelPath}';`);
   for (const plugin of pluginsWithAdminRoutes) {
-    const imp = plugin.browserImports.adminRoutes;
+    const imp = plugin.browserImports?.adminRoutes;
+    if (!imp)
+      continue;
     lines.push(`import { ${imp.exportName} } from '${imp.path}';`);
   }
   lines.push("");
@@ -713,9 +715,11 @@ ${globalItems},
     }
   }
   if (pluginsWithAdminRoutes.length > 0) {
-    const pluginItems = pluginsWithAdminRoutes.map((p) => {
-      const imp = p.browserImports.adminRoutes;
-      return `		{ name: ${JSON.stringify(p.name)}, adminRoutes: ${imp.exportName} }`;
+    const pluginItems = pluginsWithAdminRoutes.flatMap((p) => {
+      const imp = p.browserImports?.adminRoutes;
+      if (!imp)
+        return [];
+      return [`		{ name: ${JSON.stringify(p.name)}, adminRoutes: ${imp.exportName} }`];
     }).join(",\n");
     lines.push(`	plugins: [
 ${pluginItems},

package/src/index.cjs

@@ -128,6 +128,8 @@ function getUploadFieldMapping(config) {
   if (!isUploadCollection(config))
     return null;
   const u = config.upload;
+  if (!u)
+    return null;
   return {
     filename: u.filenameField ?? "filename",
     mimeType: u.mimeTypeField ?? "mimeType",
@@ -586,7 +588,7 @@ function isOwner(ownerField = "createdBy") {
 function resolveMigrationMode(mode) {
   if (mode === "push" || mode === "migrate")
     return mode;
-  const env = process.env["NODE_ENV"];
+  const env = globalThis["process"]?.env?.["NODE_ENV"];
   if (env === "production")
     return "migrate";
   return "push";

package/src/index.d.ts

@@ -13,3 +13,5 @@ export * from './lib/storage';
 export * from './lib/seeding';
 export * from './lib/versions';
 export * from './lib/migrations';
+export * from './lib/queue';
+export * from './lib/cron';

package/src/index.js

@@ -47,6 +47,8 @@ function getUploadFieldMapping(config) {
   if (!isUploadCollection(config))
     return null;
   const u = config.upload;
+  if (!u)
+    return null;
   return {
     filename: u.filenameField ?? "filename",
     mimeType: u.mimeTypeField ?? "mimeType",
@@ -505,7 +507,7 @@ function isOwner(ownerField = "createdBy") {
 function resolveMigrationMode(mode) {
   if (mode === "push" || mode === "migrate")
     return mode;
-  const env = process.env["NODE_ENV"];
+  const env = globalThis["process"]?.env?.["NODE_ENV"];
   if (env === "production")
     return "migrate";
   return "push";

package/src/lib/cron/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cron module for Momentum CMS
+ * Defines types for recurring job schedules
+ */
+import type { JobPriority } from '../queue';
+/**
+ * A recurring job schedule definition.
+ * Used by the cron plugin to periodically enqueue jobs into the queue.
+ */
+export interface RecurringJobDefinition {
+    /** Unique name for this recurring schedule */
+    name: string;
+    /** Job type to enqueue (must match a registered handler in the queue plugin) */
+    type: string;
+    /** Cron expression (5-field: minute hour day-of-month month day-of-week) */
+    cron: string;
+    /** Job payload */
+    payload?: unknown;
+    /** Queue name. @default 'default' */
+    queue?: string;
+    /** Priority (0=highest, 9=lowest). @default 5 */
+    priority?: JobPriority;
+    /** Maximum retry attempts. @default 3 */
+    maxRetries?: number;
+    /** Timeout in ms. @default 30000 */
+    timeout?: number;
+    /** Whether the schedule is enabled. @default true */
+    enabled?: boolean;
+}

package/src/lib/fields/field.types.d.ts

@@ -20,8 +20,8 @@ export interface FieldAdminConfig {
     readOnly?: boolean;
     hidden?: boolean;
     placeholder?: string;
-    /** For blocks fields: editor rendering mode. 'visual' enables the WYSIWYG block editor. */
-    editor?: 'visual' | 'form';
+    /** Editor rendering mode. 'visual' enables WYSIWYG block editor; 'email-builder' enables email template builder; 'form-builder' enables form schema builder for json fields. */
+    editor?: 'visual' | 'form' | 'email-builder' | 'form-builder';
     /** Render this group field as a collapsible accordion section */
     collapsible?: boolean;
     /** Whether the collapsible section starts expanded (default: false) */

package/src/lib/plugins.d.ts

@@ -5,7 +5,7 @@
  * These live in @momentumcms/core to avoid circular dependencies.
  * Runtime implementations (PluginRunner, etc.) live in @momentumcms/plugins/core.
  */
-import type { CollectionConfig } from './collections';
+import type { CollectionConfig, UserContext } from './collections';
 import type { MomentumConfig } from './config';
 /**
  * Descriptor for Express middleware/routes that a plugin wants auto-mounted.
@@ -127,6 +127,12 @@ export interface MomentumAPI {
     collection(slug: string): unknown;
     /** Get the current config */
     getConfig(): MomentumConfig;
+    /** Return a new API instance with merged context (immutable). */
+    setContext(ctx: {
+        user?: UserContext;
+        depth?: number;
+        showHiddenFields?: boolean;
+    }): MomentumAPI;
 }
 /**
  * A Momentum CMS plugin.

package/src/lib/queue/index.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Queue module for Momentum CMS
+ * Defines interfaces for job queue adapters
+ */
+/**
+ * Job status lifecycle:
+ * pending -> active -> completed
+ *                   -> failed (retries remain) -> pending (retry)
+ *                   -> dead (max retries exceeded)
+ */
+export type JobStatus = 'pending' | 'active' | 'completed' | 'failed' | 'dead';
+/**
+ * Job priority levels. Lower number = higher priority.
+ * 0 is the highest priority, 9 is the lowest.
+ */
+export type JobPriority = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+/**
+ * Backoff strategy for job retries.
+ */
+export interface BackoffStrategy {
+    /** Backoff type */
+    type: 'exponential' | 'linear' | 'fixed';
+    /** Base delay in milliseconds */
+    delay: number;
+    /** Maximum delay in milliseconds (cap for exponential). @default 300000 (5 minutes) */
+    maxDelay?: number;
+}
+/**
+ * Options when enqueuing a job.
+ */
+export interface EnqueueOptions {
+    /** Queue name. @default 'default' */
+    queue?: string;
+    /** Priority (0=highest, 9=lowest). @default 5 */
+    priority?: JobPriority;
+    /** Delay execution until this Date (ISO string or Date). */
+    runAt?: string | Date;
+    /** Maximum retry attempts. @default 3 */
+    maxRetries?: number;
+    /** Backoff strategy for retries. @default { type: 'exponential', delay: 1000 } */
+    backoff?: BackoffStrategy;
+    /** Maximum time in ms a job can run before being considered stalled. @default 30000 */
+    timeout?: number;
+    /** Unique key for deduplication. If a pending/active job with this key exists, the new job is skipped. */
+    uniqueKey?: string;
+    /** Arbitrary metadata attached to the job (not part of the handler payload). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A job record as stored/returned by the adapter.
+ */
+export interface Job<T = unknown> {
+    /** Unique job ID */
+    id: string;
+    /** Job type name (matches a registered handler) */
+    type: string;
+    /** Job payload (serialized as JSON) */
+    payload: T;
+    /** Current job status */
+    status: JobStatus;
+    /** Queue name */
+    queue: string;
+    /** Priority (0-9) */
+    priority: JobPriority;
+    /** Number of attempts made */
+    attempts: number;
+    /** Maximum retry attempts */
+    maxRetries: number;
+    /** Backoff configuration */
+    backoff: BackoffStrategy;
+    /** Timeout in milliseconds */
+    timeout: number;
+    /** Unique deduplication key */
+    uniqueKey?: string;
+    /** When the job should run (null = immediately) */
+    runAt: string | null;
+    /** When the job was last started */
+    startedAt?: string;
+    /** When the job completed or failed permanently */
+    finishedAt?: string;
+    /** Last error message (if failed/dead) */
+    lastError?: string;
+    /** Arbitrary metadata */
+    metadata?: Record<string, unknown>;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+/**
+ * Options for fetching the next batch of jobs to process.
+ */
+export interface FetchJobsOptions {
+    /** Queue name to fetch from. @default 'default' */
+    queue?: string;
+    /** Maximum number of jobs to fetch. @default 1 */
+    limit?: number;
+}
+/**
+ * Options for querying jobs (admin dashboard, monitoring).
+ */
+export interface JobQueryOptions {
+    /** Filter by status */
+    status?: JobStatus;
+    /** Filter by queue name */
+    queue?: string;
+    /** Filter by job type */
+    type?: string;
+    /** Pagination limit. @default 50 */
+    limit?: number;
+    /** Pagination page (1-based). @default 1 */
+    page?: number;
+}
+/**
+ * Result of a job query.
+ */
+export interface JobQueryResult {
+    jobs: Job[];
+    total: number;
+    page: number;
+    limit: number;
+}
+/**
+ * Queue statistics for monitoring.
+ */
+export interface QueueStats {
+    /** Queue name */
+    queue: string;
+    /** Count of jobs by status */
+    counts: Record<JobStatus, number>;
+    /** Oldest pending job age in milliseconds */
+    oldestPendingAge?: number;
+}
+/**
+ * Queue adapter interface.
+ * Implement this interface to create custom queue backends (PostgreSQL, Redis, etc.).
+ */
+export interface QueueAdapter {
+    /**
+     * Initialize the queue backend (create indexes, etc.).
+     * Called once during server startup after collection tables are created.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Enqueue a new job.
+     * @param type - Job type name (matches a registered handler)
+     * @param payload - Job payload data
+     * @param options - Enqueue options
+     * @returns The created job record
+     */
+    enqueue(type: string, payload: unknown, options?: EnqueueOptions): Promise<Job>;
+    /**
+     * Fetch the next batch of jobs ready for processing.
+     * Must use atomic locking (e.g., SKIP LOCKED) to prevent double-processing.
+     * Jobs are returned in priority order (lowest number first), then by runAt/createdAt.
+     */
+    fetchJobs(options?: FetchJobsOptions): Promise<Job[]>;
+    /**
+     * Mark a job as completed.
+     */
+    completeJob(jobId: string): Promise<void>;
+    /**
+     * Mark a job as failed. If retries remain, schedules the next attempt.
+     * If max retries exceeded, moves to 'dead' status.
+     */
+    failJob(jobId: string, error: string): Promise<void>;
+    /**
+     * Query jobs for monitoring/admin UI.
+     */
+    queryJobs(options?: JobQueryOptions): Promise<JobQueryResult>;
+    /**
+     * Get statistics for one or all queues.
+     * @param queue - Optional queue name (all queues if omitted)
+     */
+    getStats(queue?: string): Promise<QueueStats[]>;
+    /**
+     * Get a single job by ID.
+     * @returns The job record, or null if not found
+     */
+    getJob(jobId: string): Promise<Job | null>;
+    /**
+     * Delete a specific job by ID.
+     * @returns True if deleted
+     */
+    deleteJob(jobId: string): Promise<boolean>;
+    /**
+     * Purge completed/dead jobs older than the given age.
+     * @param olderThanMs - Age threshold in milliseconds
+     * @param status - Status to purge. @default 'completed'
+     * @returns Number of jobs purged
+     */
+    purgeJobs(olderThanMs: number, status?: 'completed' | 'dead'): Promise<number>;
+    /**
+     * Retry a dead job (move it back to pending with reset attempts).
+     * @returns The updated job
+     */
+    retryJob(jobId: string): Promise<Job>;
+    /**
+     * Detect and recover stalled jobs (active jobs that exceeded their timeout).
+     * Moves them back to pending for retry, or to dead if maxRetries exceeded.
+     * @returns Number of jobs recovered
+     */
+    recoverStalledJobs(): Promise<number>;
+    /**
+     * Graceful shutdown. Releases any held resources.
+     */
+    shutdown(): Promise<void>;
+}

package/src/lib/storage/index.d.ts

@@ -12,8 +12,8 @@ export interface UploadedFile {
     mimeType: string;
     /** File size in bytes */
     size: number;
-    /** File content as Buffer */
-    buffer: Buffer;
+    /** File content (Uint8Array for universal compat; Node Buffer extends Uint8Array) */
+    buffer: Uint8Array;
 }
 /**
  * Represents a file after it has been stored.
@@ -82,5 +82,5 @@ export interface StorageAdapter {
      * @param path - The storage path/key
      * @returns The file as a Buffer, or null if not found
      */
-    read?(path: string): Promise<Buffer | null>;
+    read?(path: string): Promise<Uint8Array | null>;
 }