create-jen-app 1.2.1 → 1.2.3

package/templates/static/lib/jdb/types.d.ts

@@ -1,46 +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 = {
-    root: string;
-    inMemory?: boolean;
+  /** 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> & {
-    _id: string;
-    _created: number;
-    _updated: number;
+  /** 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;
 };
-export type FilterOperator = "$eq" | "$ne" | "$gt" | "$gte" | "$lt" | "$lte" | "$in" | "$nin" | "$regex";
+/**
+ * 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] | {
+  [K in keyof T]?:
+    | T[K]
+    | {
         [op in FilterOperator]?: any;
-    };
+      };
 } & {
-    $or?: Filter<T>[];
-    $and?: Filter<T>[];
+  /** 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>[];
 };
-export type UpdateOperator = "$set" | "$unset" | "$inc" | "$push" | "$pull";
+/**
+ * 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>;
+  [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 = {
-    limit?: number;
-    skip?: number;
-    sort?: Record<string, 1 | -1>;
+  /** 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 {
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    collection(name: string): ICollection;
+  /** 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: string;
-    insert(doc: Omit<T, "_id" | "_created" | "_updated"> & {
-        _id?: string;
-    }): Promise<T>;
-    insertMany(docs: (Omit<T, "_id" | "_created" | "_updated"> & {
-        _id?: string;
-    })[]): Promise<T[]>;
-    findOne(filter: Filter<T>): Promise<T | null>;
-    find(filter: Filter<T>, options?: QueryOptions): Promise<T[]>;
-    update(filter: Filter<T>, update: Update<T>, multi?: boolean): Promise<number>;
-    delete(filter: Filter<T>, multi?: boolean): Promise<number>;
-    count(filter: Filter<T>): Promise<number>;
+  /** 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/static/lib/jdb/utils.d.ts

@@ -1,6 +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;

package/templates/static/lib/jdb/utils.js

@@ -17,125 +17,177 @@
  */
 import fs from "fs/promises";
 import crypto from "crypto";
+/**
+ * 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 async function ensureDir(dir) {
-    try {
-        await fs.access(dir);
-    }
-    catch {
-        await fs.mkdir(dir, { recursive: true });
-    }
+  try {
+    await fs.access(dir);
+  } catch {
+    await fs.mkdir(dir, { recursive: true });
+  }
 }
+/**
+ * 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 async function readJSON(file) {
-    try {
-        const data = await fs.readFile(file, "utf-8");
-        return JSON.parse(data);
-    }
-    catch (e) {
-        if (e.code === "ENOENT")
-            return null;
-        throw e;
-    }
+  try {
+    const data = await fs.readFile(file, "utf-8");
+    return JSON.parse(data);
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
 }
+/**
+ * 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 async function writeJSON(file, data) {
-    const tempFile = `${file}.tmp`;
-    await fs.writeFile(tempFile, JSON.stringify(data, null, 2));
-    await fs.rename(tempFile, file);
+  const tempFile = `${file}.tmp`;
+  await fs.writeFile(tempFile, JSON.stringify(data, null, 2));
+  await fs.rename(tempFile, file);
 }
+/**
+ * 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 function generateId() {
-    return crypto.randomUUID();
+  return crypto.randomUUID();
 }
+/**
+ * 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 function matchFilter(doc, filter) {
-    for (const key in filter) {
-        if (key === "$or") {
-            if (!filter.$or.some((f) => matchFilter(doc, f)))
-                return false;
-            continue;
-        }
-        if (key === "$and") {
-            if (!filter.$and.every((f) => matchFilter(doc, f)))
-                return false;
-            continue;
-        }
-        const val = doc[key];
-        const cond = filter[key];
-        if (typeof cond === "object" && cond !== null && !Array.isArray(cond)) {
-            for (const op in cond) {
-                const target = cond[op];
-                switch (op) {
-                    case "$eq":
-                        if (val !== target)
-                            return false;
-                        break;
-                    case "$ne":
-                        if (val === target)
-                            return false;
-                        break;
-                    case "$gt":
-                        if (!(val > target))
-                            return false;
-                        break;
-                    case "$gte":
-                        if (!(val >= target))
-                            return false;
-                        break;
-                    case "$lt":
-                        if (!(val < target))
-                            return false;
-                        break;
-                    case "$lte":
-                        if (!(val <= target))
-                            return false;
-                        break;
-                    case "$in":
-                        if (!target.includes(val))
-                            return false;
-                        break;
-                    case "$nin":
-                        if (target.includes(val))
-                            return false;
-                        break;
-                    case "$regex":
-                        if (!new RegExp(target).test(val))
-                            return false;
-                        break;
-                }
-            }
-        }
-        else {
-            if (val !== cond)
-                return false;
+  for (const key in filter) {
+    if (key === "$or") {
+      // OR: at least one filter must match
+      if (!filter.$or.some((f) => matchFilter(doc, f))) return false;
+      continue;
+    }
+    if (key === "$and") {
+      // AND: all filters must match
+      if (!filter.$and.every((f) => matchFilter(doc, f))) return false;
+      continue;
+    }
+    const val = doc[key];
+    const cond = filter[key];
+    // If condition is an object (not array), it contains operators
+    if (typeof cond === "object" && cond !== null && !Array.isArray(cond)) {
+      for (const op in cond) {
+        const target = cond[op];
+        switch (op) {
+          case "$eq":
+            if (val !== target) return false;
+            break;
+          case "$ne":
+            if (val === target) return false;
+            break;
+          case "$gt":
+            if (!(val > target)) return false;
+            break;
+          case "$gte":
+            if (!(val >= target)) return false;
+            break;
+          case "$lt":
+            if (!(val < target)) return false;
+            break;
+          case "$lte":
+            if (!(val <= target)) return false;
+            break;
+          case "$in":
+            if (!target.includes(val)) return false;
+            break;
+          case "$nin":
+            if (target.includes(val)) return false;
+            break;
+          case "$regex":
+            if (!new RegExp(target).test(val)) return false;
+            break;
         }
+      }
+    } else {
+      // Simple equality check
+      if (val !== cond) return false;
     }
-    return true;
+  }
+  return true;
 }
+/**
+ * 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 function applyUpdate(doc, update) {
-    const now = Date.now();
-    doc._updated = now;
-    for (const op in update) {
-        const fields = update[op];
-        for (const key in fields) {
-            const val = fields[key];
-            switch (op) {
-                case "$set":
-                    doc[key] = val;
-                    break;
-                case "$unset":
-                    delete doc[key];
-                    break;
-                case "$inc":
-                    doc[key] = (doc[key] || 0) + val;
-                    break;
-                case "$push":
-                    if (!Array.isArray(doc[key]))
-                        doc[key] = [];
-                    doc[key].push(val);
-                    break;
-                case "$pull":
-                    if (Array.isArray(doc[key])) {
-                        doc[key] = doc[key].filter((item) => item !== val);
-                    }
-                    break;
-            }
-        }
+  const now = Date.now();
+  doc._updated = now;
+  for (const op in update) {
+    const fields = update[op];
+    for (const key in fields) {
+      const val = fields[key];
+      switch (op) {
+        case "$set":
+          // Set field to the specified value
+          doc[key] = val;
+          break;
+        case "$unset":
+          // Remove the field from the document
+          delete doc[key];
+          break;
+        case "$inc":
+          // Increment numeric field by the specified amount
+          doc[key] = (doc[key] || 0) + val;
+          break;
+        case "$push":
+          // Append to array (create array if doesn't exist)
+          if (!Array.isArray(doc[key])) doc[key] = [];
+          doc[key].push(val);
+          break;
+        case "$pull":
+          // Remove all occurrences of value from array
+          if (Array.isArray(doc[key])) {
+            doc[key] = doc[key].filter((item) => item !== val);
+          }
+          break;
+      }
     }
+  }
 }

package/templates/static/lib/middleware/builtins/body-parser.d.ts

@@ -1 +1,16 @@
+/**
+ * Request body parsing middleware.
+ * Reads and parses the request body based on Content-Type header.
+ * Supports JSON, URL-encoded form data, and plain text.
+ *
+ * GET and HEAD requests are passed through without parsing since they have no body.
+ * Parsed body is available in ctx.body. If parsing fails, the raw string is stored
+ * and an error message is attached to ctx.parseError for error handling downstream.
+ *
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(bodyParser);
+ * // ctx.body is now populated with parsed request body
+ */
 export function bodyParser(ctx: any, next: any): Promise<any>;