create-jen-app 1.2.2 → 1.2.4

package/templates/ssr-isr/lib/jdb/engine.js

@@ -0,0 +1,275 @@
+import path from "path";
+import {
+  ensureDir,
+  readJSON,
+  writeJSON,
+  generateId,
+  matchFilter,
+  applyUpdate,
+} from "./utils";
+/**
+ * In-memory representation of a single collection.
+ * Manages document storage, serialization, and basic file I/O.
+ * Supports lazy loading of data from disk and deferred save operations to batch writes.
+ *
+ * @template T Document type, must extend the Document base type.
+ */
+class JDBCollection {
+  name;
+  dir;
+  inMemory;
+  /** Absolute path to the .jdb file for this collection. */
+  file;
+  /** In-memory array of documents. */
+  data = [];
+  /** Flag indicating whether the data has been loaded from disk. */
+  loaded = false;
+  /** Flag indicating a save operation is currently in progress. */
+  saving = false;
+  /** Flag indicating a save was requested while another save was in progress. Triggers another save after current one completes. */
+  queueSave = false;
+  /**
+   * Create a new collection instance.
+   * Does not load data until an operation requires it (lazy loading).
+   *
+   * @param name Name of the collection.
+   * @param dir Directory where collection files are stored.
+   * @param inMemory If true, data is never persisted to disk.
+   */
+  constructor(name, dir, inMemory) {
+    this.name = name;
+    this.dir = dir;
+    this.inMemory = inMemory;
+    this.file = path.join(dir, `${name}.jdb`);
+  }
+  /**
+   * Load collection data from disk on first access.
+   * Uses lazy loading to defer file I/O until actually needed.
+   * In-memory collections skip disk reads entirely.
+   * Idempotent: subsequent calls return immediately if already loaded.
+   */
+  async load() {
+    if (this.loaded) return;
+    if (!this.inMemory) {
+      await ensureDir(this.dir);
+      const content = await readJSON(this.file);
+      this.data = content || [];
+    }
+    this.loaded = true;
+  }
+  /**
+   * Persist collection data to disk.
+   * Uses a queue mechanism to batch multiple rapid modifications into a single write.
+   * If a save is already in progress, queues the next save to run after current one completes.
+   * In-memory collections skip disk writes entirely.
+   */
+  async save() {
+    if (this.inMemory) return;
+    if (this.saving) {
+      this.queueSave = true;
+      return;
+    }
+    this.saving = true;
+    try {
+      await writeJSON(this.file, this.data);
+    } finally {
+      this.saving = false;
+      if (this.queueSave) {
+        this.queueSave = false;
+        this.save();
+      }
+    }
+  }
+  /**
+   * Insert a single document into the collection.
+   * Automatically assigns a UUID for _id (if not provided) and timestamps for _created and _updated.
+   * Queues a save operation to persist the document.
+   *
+   * @param doc The document to insert, without system fields.
+   * @returns The inserted document with _id, _created, and _updated populated.
+   */
+  async insert(doc) {
+    await this.load();
+    const now = Date.now();
+    const newDoc = {
+      _id: doc._id || generateId(),
+      _created: now,
+      _updated: now,
+      ...doc,
+    };
+    this.data.push(newDoc);
+    this.save();
+    return newDoc;
+  }
+  /**
+   * Insert multiple documents into the collection atomically.
+   * All documents are assigned the same _created timestamp.
+   * Queues a single save operation to persist all documents.
+   *
+   * @param docs Array of documents to insert.
+   * @returns Array of inserted documents with all system fields populated.
+   */
+  async insertMany(docs) {
+    await this.load();
+    const now = Date.now();
+    const newDocs = docs.map((doc) => ({
+      _id: doc._id || generateId(),
+      _created: now,
+      _updated: now,
+      ...doc,
+    }));
+    this.data.push(...newDocs);
+    this.save();
+    return newDocs;
+  }
+  /**
+   * Find the first document matching the filter.
+   *
+   * @param filter Query filter to apply.
+   * @returns The first matching document, or null if no match found.
+   */
+  async findOne(filter) {
+    await this.load();
+    return this.data.find((doc) => matchFilter(doc, filter)) || null;
+  }
+  /**
+   * Find all documents matching the filter with optional sorting and pagination.
+   * Applies sort, skip, and limit in that order for correct pagination behavior.
+   *
+   * @param filter Query filter to apply.
+   * @param options Optional QueryOptions for sorting, skipping, and limiting results.
+   * @returns Array of matching documents (empty array if no matches).
+   */
+  async find(filter, options) {
+    await this.load();
+    let result = this.data.filter((doc) => matchFilter(doc, filter));
+    if (options?.sort) {
+      const sortKeys = Object.keys(options.sort);
+      result.sort((a, b) => {
+        for (const key of sortKeys) {
+          const dir = options.sort[key];
+          if (a[key] < b[key]) return -1 * dir;
+          if (a[key] > b[key]) return 1 * dir;
+        }
+        return 0;
+      });
+    }
+    if (options?.skip) {
+      result = result.slice(options.skip);
+    }
+    if (options?.limit) {
+      result = result.slice(0, options.limit);
+    }
+    return result;
+  }
+  /**
+   * Update document(s) matching the filter.
+   * Applies update operators atomically and updates the _updated timestamp.
+   * By default, updates only the first matching document. Set multi=true to update all.
+   *
+   * @param filter Query filter to select documents to update.
+   * @param update Update operators and values to apply.
+   * @param multi If false (default), updates only first match. If true, updates all matches.
+   * @returns Count of documents updated.
+   */
+  async update(filter, update, multi = false) {
+    await this.load();
+    let count = 0;
+    for (const doc of this.data) {
+      if (matchFilter(doc, filter)) {
+        applyUpdate(doc, update);
+        count++;
+        if (!multi) break;
+      }
+    }
+    if (count > 0) this.save();
+    return count;
+  }
+  /**
+   * Delete document(s) matching the filter.
+   * By default, deletes only the first matching document. Set multi=true to delete all.
+   *
+   * @param filter Query filter to select documents to delete.
+   * @param multi If false (default), deletes only first match. If true, deletes all matches.
+   * @returns Count of documents deleted.
+   */
+  async delete(filter, multi = false) {
+    await this.load();
+    const originalLen = this.data.length;
+    if (!multi) {
+      const index = this.data.findIndex((doc) => matchFilter(doc, filter));
+      if (index !== -1) {
+        this.data.splice(index, 1);
+        this.save();
+        return 1;
+      }
+      return 0;
+    } else {
+      this.data = this.data.filter((doc) => !matchFilter(doc, filter));
+      const deleted = originalLen - this.data.length;
+      if (deleted > 0) this.save();
+      return deleted;
+    }
+  }
+  /**
+   * Count documents matching the filter.
+   *
+   * @param filter Query filter to apply.
+   * @returns Number of documents matching the filter.
+   */
+  async count(filter) {
+    await this.load();
+    return this.data.filter((doc) => matchFilter(doc, filter)).length;
+  }
+}
+/**
+ * File-based database engine implementation.
+ * Stores collections as JSON files in the configured directory.
+ * Provides lazy collection initialization and in-memory option for testing.
+ */
+export class JDBEngine {
+  config;
+  /** Cached collection instances. Created on demand and reused for subsequent accesses. */
+  collections = new Map();
+  /**
+   * Create a new database engine instance.
+   *
+   * @param config Configuration specifying storage root directory and memory mode.
+   */
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Establish database connection by ensuring the storage root directory exists.
+   * Creates the directory recursively if it doesn't exist.
+   */
+  async connect() {
+    await ensureDir(this.config.root);
+  }
+  /**
+   * Close database connection and clean up resources.
+   * Currently a no-op for file-based storage, but provided for compatibility with IDatabaseEngine interface.
+   * Future versions may flush pending writes or close file handles here.
+   */
+  async disconnect() {
+    // No-op for file based, maybe ensure all saves are flushed
+  }
+  /**
+   * Get or create a collection by name.
+   * Collections are cached after first access, so subsequent calls return the same instance.
+   * Uses lazy initialization: data is not loaded from disk until the collection is accessed.
+   *
+   * @template T Document type for the collection.
+   * @param name Unique name for the collection. Used to generate the .jdb filename.
+   * @returns Collection instance for CRUD operations.
+   */
+  collection(name) {
+    if (!this.collections.has(name)) {
+      this.collections.set(
+        name,
+        new JDBCollection(name, this.config.root, !!this.config.inMemory),
+      );
+    }
+    return this.collections.get(name);
+  }
+}

package/templates/ssr-isr/lib/jdb/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * JDB (Jen Database) - A lightweight embedded JSON database for Jen.js applications.
+ *
+ * JDB provides MongoDB-like CRUD operations with file-based or in-memory storage.
+ * Perfect for small to medium applications that need data persistence without external dependencies.
+ *
+ * Features:
+ * - MongoDB-like query syntax with filter operators ($eq, $gt, $in, $regex, etc.)
+ * - Atomic update operations ($set, $inc, $push, etc.)
+ * - Pagination, sorting, and filtering
+ * - Lazy loading and deferred writes for performance
+ * - In-memory mode for testing
+ * - Simple JSON file format for easy inspection and migration
+ *
+ * @example
+ * import { JDBEngine, type ICollection, type Document } from '@src/jdb';
+ *
+ * interface User extends Document {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * const db = new JDBEngine({ root: './data' });
+ * await db.connect();
+ *
+ * const users = db.collection<User>('users');
+ * const user = await users.insert({ name: 'John', email: 'john@example.com', age: 30 });
+ * const found = await users.findOne({ email: 'john@example.com' });
+ * await users.update({ _id: user._id }, { $set: { age: 31 } });
+ * await users.delete({ _id: user._id });
+ */
+export * from "./types";
+export { JDBEngine } from "./engine";

package/templates/ssr-isr/lib/jdb/index.js

@@ -0,0 +1,34 @@
+/**
+ * JDB (Jen Database) - A lightweight embedded JSON database for Jen.js applications.
+ *
+ * JDB provides MongoDB-like CRUD operations with file-based or in-memory storage.
+ * Perfect for small to medium applications that need data persistence without external dependencies.
+ *
+ * Features:
+ * - MongoDB-like query syntax with filter operators ($eq, $gt, $in, $regex, etc.)
+ * - Atomic update operations ($set, $inc, $push, etc.)
+ * - Pagination, sorting, and filtering
+ * - Lazy loading and deferred writes for performance
+ * - In-memory mode for testing
+ * - Simple JSON file format for easy inspection and migration
+ *
+ * @example
+ * import { JDBEngine, type ICollection, type Document } from '@src/jdb';
+ *
+ * interface User extends Document {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * const db = new JDBEngine({ root: './data' });
+ * await db.connect();
+ *
+ * const users = db.collection<User>('users');
+ * const user = await users.insert({ name: 'John', email: 'john@example.com', age: 30 });
+ * const found = await users.findOne({ email: 'john@example.com' });
+ * await users.update({ _id: user._id }, { $set: { age: 31 } });
+ * await users.delete({ _id: user._id });
+ */
+export * from "./types";
+export { JDBEngine } from "./engine";

package/templates/ssr-isr/lib/jdb/types.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Configuration for the JDB (Jen Database) engine.
+ * Specifies the storage location and memory mode for data persistence.
+ *
+ * @example
+ * const config: JDBConfig = {
+ *   root: './data/jdb',
+ *   inMemory: false
+ * };
+ */
+export type JDBConfig = {
+  /** Absolute or relative path to directory where .jdb collection files are stored. */
+  root: string;
+  /** If true, data is stored only in memory; files are not written to disk. Useful for testing. */
+  inMemory?: boolean;
+};
+/**
+ * Base document type for all collections.
+ * Every document in a JDB collection must include system metadata fields.
+ * These fields are automatically managed and should not be manually modified.
+ *
+ * @example
+ * interface User extends Document {
+ *   name: string;
+ *   email: string;
+ * }
+ */
+export type Document = Record<string, any> & {
+  /** Unique identifier automatically generated as a UUID. */
+  _id: string;
+  /** Timestamp (milliseconds) when the document was created. Set once, never changes. */
+  _created: number;
+  /** Timestamp (milliseconds) when the document was last updated. Updated on every modification. */
+  _updated: number;
+};
+/**
+ * Filter operators for querying documents.
+ * Support MongoDB-like query syntax for flexible filtering.
+ */
+export type FilterOperator =
+  | "$eq" /** Equal to the specified value. */
+  | "$ne" /** Not equal to the specified value. */
+  | "$gt" /** Greater than the specified value. */
+  | "$gte" /** Greater than or equal to the specified value. */
+  | "$lt" /** Less than the specified value. */
+  | "$lte" /** Less than or equal to the specified value. */
+  | "$in" /** Value is in the specified array. */
+  | "$nin" /** Value is not in the specified array. */
+  | "$regex"; /** Value matches the specified regular expression pattern. */
+/**
+ * Filter object for querying documents.
+ * Supports both simple equality checks and complex operator-based conditions.
+ * Supports logical combinations via $and and $or.
+ *
+ * @example
+ * // Simple equality
+ * const filter1: Filter<User> = { name: 'John' };
+ *
+ * // Operator-based conditions
+ * const filter2: Filter<User> = { age: { $gte: 18 } };
+ *
+ * // Logical operators
+ * const filter3: Filter<User> = {
+ *   $or: [{ name: 'John' }, { name: 'Jane' }]
+ * };
+ */
+export type Filter<T = any> = {
+  [K in keyof T]?:
+    | T[K]
+    | {
+        [op in FilterOperator]?: any;
+      };
+} & {
+  /** Logical OR: document matches if it matches any filter in the array. */
+  $or?: Filter<T>[];
+  /** Logical AND: document matches if it matches all filters in the array. */
+  $and?: Filter<T>[];
+};
+/**
+ * Update operators for modifying documents.
+ * Enable atomic field modifications without replacing the entire document.
+ */
+export type UpdateOperator =
+  | "$set" /** Set field value(s). Overwrites existing values. */
+  | "$unset" /** Remove field(s) from the document. */
+  | "$inc" /** Increment numeric field(s) by the specified amount. */
+  | "$push" /** Append value(s) to an array field. Creates array if it doesn't exist. */
+  | "$pull"; /** Remove all occurrences of value(s) from an array field. */
+/**
+ * Update object for modifying documents.
+ * Specifies which fields to change and how, using update operators.
+ *
+ * @example
+ * // Set operation
+ * const update1: Update<User> = { $set: { name: 'Jane', age: 30 } };
+ *
+ * // Multiple operators
+ * const update2: Update<User> = {
+ *   $set: { status: 'active' },
+ *   $inc: { loginCount: 1 }
+ * };
+ */
+export type Update<T = any> = {
+  [op in UpdateOperator]?: Partial<T> | Record<string, any>;
+};
+/**
+ * Options for controlling query behavior.
+ * Supports sorting, limiting, and skipping results for pagination and ordering.
+ *
+ * @example
+ * const options: QueryOptions = {
+ *   sort: { createdAt: -1 },
+ *   skip: 10,
+ *   limit: 20
+ * };
+ */
+export type QueryOptions = {
+  /** Maximum number of documents to return. */
+  limit?: number;
+  /** Number of documents to skip before returning results. Used for pagination. */
+  skip?: number;
+  /** Sort specification. Value 1 for ascending, -1 for descending. Multiple fields supported. */
+  sort?: Record<string, 1 | -1>;
+};
+/**
+ * Abstract interface for a database engine.
+ * Defines the contract that database implementations must follow.
+ * Handles connection lifecycle and provides access to collections.
+ */
+export interface IDatabaseEngine {
+  /** Establish connection to the database and perform initialization. */
+  connect(): Promise<void>;
+  /** Close connection and clean up resources. */
+  disconnect(): Promise<void>;
+  /** Get or create a collection by name. Creates a new instance if collection doesn't exist. */
+  collection(name: string): ICollection;
+}
+/**
+ * Collection interface for CRUD operations on documents.
+ * Provides MongoDB-like methods for inserting, querying, updating, and deleting documents.
+ * All operations are async to support file I/O and potential distributed backends.
+ *
+ * @template T Document type, must extend Document base type with _id, _created, _updated.
+ *
+ * @example
+ * interface BlogPost extends Document {
+ *   title: string;
+ *   content: string;
+ *   published: boolean;
+ * }
+ *
+ * const posts: ICollection<BlogPost> = db.collection('posts');
+ * const post = await posts.insert({ title: 'Hello', content: '...' });
+ * const found = await posts.findOne({ _id: post._id });
+ */
+export interface ICollection<T extends Document = Document> {
+  /** Name of the collection. */
+  name: string;
+  /**
+   * Insert a single document into the collection.
+   * Automatically generates _id, _created, and _updated if not provided.
+   *
+   * @param doc The document to insert. _id, _created, _updated are optional.
+   * @returns The inserted document with all system fields populated.
+   */
+  insert(
+    doc: Omit<T, "_id" | "_created" | "_updated"> & {
+      _id?: string;
+    },
+  ): Promise<T>;
+  /**
+   * Insert multiple documents into the collection atomically.
+   * All documents are assigned the same _created timestamp.
+   *
+   * @param docs Array of documents to insert.
+   * @returns Array of inserted documents with all system fields populated.
+   */
+  insertMany(
+    docs: (Omit<T, "_id" | "_created" | "_updated"> & {
+      _id?: string;
+    })[],
+  ): Promise<T[]>;
+  /**
+   * Find the first document matching the filter.
+   * Returns null if no match found.
+   *
+   * @param filter Query filter to match documents.
+   * @returns The first matching document, or null if none found.
+   */
+  findOne(filter: Filter<T>): Promise<T | null>;
+  /**
+   * Find all documents matching the filter with optional sorting and pagination.
+   *
+   * @param filter Query filter to match documents.
+   * @param options Optional sorting, limiting, and pagination options.
+   * @returns Array of matching documents (empty array if no matches).
+   */
+  find(filter: Filter<T>, options?: QueryOptions): Promise<T[]>;
+  /**
+   * Update document(s) matching the filter.
+   * Updates _updated timestamp automatically.
+   *
+   * @param filter Query filter to select documents to update.
+   * @param update Update operators and values to apply.
+   * @param multi If false (default), updates only first match. If true, updates all matches.
+   * @returns Count of documents updated.
+   */
+  update(
+    filter: Filter<T>,
+    update: Update<T>,
+    multi?: boolean,
+  ): Promise<number>;
+  /**
+   * Delete document(s) matching the filter.
+   *
+   * @param filter Query filter to select documents to delete.
+   * @param multi If false (default), deletes only first match. If true, deletes all matches.
+   * @returns Count of documents deleted.
+   */
+  delete(filter: Filter<T>, multi?: boolean): Promise<number>;
+  /**
+   * Count documents matching the filter.
+   *
+   * @param filter Query filter to match documents.
+   * @returns Number of documents matching the filter.
+   */
+  count(filter: Filter<T>): Promise<number>;
+}

package/templates/ssr-isr/lib/jdb/types.js

@@ -0,0 +1 @@
+export {};

package/templates/ssr-isr/lib/jdb/utils.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Ensure a directory exists, creating it recursively if necessary.
+ * Idempotent: does not throw if the directory already exists.
+ *
+ * @param dir Directory path to ensure exists.
+ * @throws Error if directory creation fails.
+ */
+export declare function ensureDir(dir: string): Promise<void>;
+/**
+ * Read and parse a JSON file from disk.
+ * Returns null if the file does not exist (ENOENT).
+ * Other errors (invalid JSON, permission denied, etc.) are re-thrown.
+ *
+ * @template T The expected JSON structure type.
+ * @param file Path to the JSON file to read.
+ * @returns Parsed JSON data, or null if file does not exist.
+ * @throws Error if the file exists but cannot be read or parsed.
+ */
+export declare function readJSON<T>(file: string): Promise<T | null>;
+/**
+ * Write data as JSON to a file atomically using a temporary file.
+ * Atomic writes prevent corruption if the process crashes during writing.
+ * The temporary file is renamed to the target file only after writing completes successfully.
+ *
+ * @param file Path to the target file (will be created or overwritten).
+ * @param data Object to serialize as JSON with pretty-printing (2-space indent).
+ * @throws Error if writing or renaming fails.
+ */
+export declare function writeJSON(file: string, data: any): Promise<void>;
+/**
+ * Generate a unique identifier for a new document.
+ * Uses cryptographically secure UUID v4 generation.
+ *
+ * @returns A UUID string suitable for use as a document _id.
+ */
+export declare function generateId(): string;
+/**
+ * Test whether a document matches a filter query.
+ * Supports MongoDB-like query syntax including operators ($eq, $ne, $gt, etc.) and logical operators ($or, $and).
+ * Processes each field condition and returns false if any condition fails (AND semantics).
+ * Logical operators $or and $and are processed separately with their respective semantics.
+ *
+ * @param doc The document to test.
+ * @param filter The filter query to apply.
+ * @returns True if the document matches all filter conditions, false otherwise.
+ *
+ * @example
+ * matchFilter({ name: 'John', age: 30 }, { name: 'John' }) // true
+ * matchFilter({ age: 25 }, { age: { $gte: 18 } }) // true
+ * matchFilter({ name: 'Jane' }, { $or: [{ name: 'John' }, { name: 'Jane' }] }) // true
+ */
+export declare function matchFilter(doc: any, filter: any): boolean;
+/**
+ * Apply update operators to a document, modifying it in place.
+ * Automatically updates the _updated timestamp to the current time.
+ * Supports $set, $unset, $inc, $push, and $pull operators.
+ *
+ * @param doc The document to update (modified in place).
+ * @param update Update specification with operators.
+ *
+ * @example
+ * const doc = { name: 'John', age: 30, tags: ['js'] };
+ * applyUpdate(doc, { $set: { name: 'Jane' }, $inc: { age: 1 }, $push: { tags: 'ts' } });
+ * // doc is now { name: 'Jane', age: 31, tags: ['js', 'ts'], _updated: <current-timestamp> }
+ */
+export declare function applyUpdate(doc: any, update: any): void;