@shetty4l/core 0.1.34 → 0.1.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shetty4l/core",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "Shared infrastructure primitives for Bun/TypeScript services",
   "repository": {
     "type": "git",

package/src/state/collection/decorators.ts

@@ -0,0 +1,252 @@
+/**
+ * TC39 decorators for collection persistence.
+ *
+ * Uses the same global accumulator pattern as @Persisted decorators
+ * to work around Bun's TC39 decorator quirks.
+ *
+ * @example
+ * ```ts
+ * @PersistedCollection('users')
+ * class User extends CollectionEntity {
+ *   @Id() id: string = '';
+ *   @Field('string') @Index() email: string = '';
+ *   @Field('string') name: string = '';
+ *   @Field('date') @Index(['status', 'created_at']) createdAt: Date | null = null;
+ *   @Field('string') status: string = 'active';
+ * }
+ * ```
+ */
+
+import {
+  type CollectionFieldMeta,
+  collectionMeta,
+  type FieldType,
+  type IndexMeta,
+} from "./types";
+
+/**
+ * Convert camelCase to snake_case.
+ * Handles leading uppercase (e.g., 'ID' -> 'id', not '_i_d').
+ */
+function toSnakeCase(str: string): string {
+  return str.replace(/[A-Z]/g, (letter, index) =>
+    index === 0 ? letter.toLowerCase() : `_${letter.toLowerCase()}`,
+  );
+}
+
+/**
+ * Extract property name from TC39 decorator context.
+ *
+ * TC39 field decorator context is a ClassFieldDecoratorContext object with a `name` property.
+ * This handles both the standard TC39 context object and legacy string contexts.
+ */
+function extractPropertyName(context: unknown): string {
+  if (typeof context === "object" && context !== null && "name" in context) {
+    return String((context as { name: unknown }).name);
+  }
+  return String(context);
+}
+
+/** Options for the @Field decorator. */
+export interface FieldOptions {
+  /** Custom column name. Defaults to snake_case of property name. */
+  column?: string;
+}
+
+/** Options for the @Id decorator. */
+export interface IdOptions {
+  /** Custom column name. Defaults to 'id'. */
+  column?: string;
+}
+
+// --------------------------------------------------------------------------
+// Global accumulators for pending definitions
+// --------------------------------------------------------------------------
+
+type PendingFieldDef = { column: string; type: FieldType };
+type PendingFieldsMap = Map<string, PendingFieldDef>;
+type PendingIdDef = { property: string; column: string; type: FieldType };
+type PendingIndexDef = { columns: string[] };
+
+// In Bun's TC39 implementation, field decorators run synchronously
+// before the class decorator for the same class.
+let globalPendingFields: PendingFieldsMap | null = null;
+let globalPendingId: PendingIdDef | null = null;
+let globalPendingIdCount = 0; // Track multiple @Id to detect error
+let globalPendingIndices: PendingIndexDef[] | null = null;
+
+/**
+ * Reset all global accumulator state.
+ * Called before throwing errors to prevent stale data affecting subsequent classes.
+ */
+function resetGlobalState(): void {
+  globalPendingFields = null;
+  globalPendingId = null;
+  globalPendingIdCount = 0;
+  globalPendingIndices = null;
+}
+
+/**
+ * Mark a class as a persisted collection (multi-row table).
+ *
+ * @param table - SQLite table name
+ * @throws Error if class extends another @PersistedCollection class
+ * @throws Error if no @Id field is defined
+ */
+export function PersistedCollection(table: string) {
+  // Bun's TC39 decorator: context is undefined, not ClassDecoratorContext
+  return function <T extends new (...args: unknown[]) => object>(
+    target: T,
+    _context: unknown,
+  ): T {
+    // Check prototype chain for existing @PersistedCollection class
+    let proto = Object.getPrototypeOf(target);
+    while (proto && proto !== Function.prototype) {
+      if (collectionMeta.has(proto)) {
+        const parentMeta = collectionMeta.get(proto)!;
+        resetGlobalState();
+        throw new Error(
+          `@PersistedCollection class "${target.name}" cannot extend @PersistedCollection class "${proto.name}" (table: "${parentMeta.table}"). ` +
+            `Collection classes do not support inheritance.`,
+        );
+      }
+      proto = Object.getPrototypeOf(proto);
+    }
+
+    // Check that @Id was defined
+    if (!globalPendingId) {
+      resetGlobalState();
+      throw new Error(
+        `@PersistedCollection class "${target.name}" must have exactly one @Id field.`,
+      );
+    }
+
+    // Check that only one @Id was defined for this class
+    if (globalPendingIdCount > 1) {
+      resetGlobalState();
+      throw new Error(
+        `Multiple @Id decorators found in "${target.name}". A class can only have one @Id field.`,
+      );
+    }
+
+    // Initialize metadata for this class
+    const meta = {
+      table,
+      idProperty: globalPendingId.property,
+      idColumn: globalPendingId.column,
+      idType: globalPendingId.type,
+      fields: new Map<string, CollectionFieldMeta>(),
+      indices: [] as IndexMeta[],
+    };
+
+    // Consume pending fields accumulated by @Field decorators
+    if (globalPendingFields) {
+      for (const [property, def] of globalPendingFields) {
+        meta.fields.set(property, {
+          property,
+          column: def.column,
+          type: def.type,
+        });
+      }
+      globalPendingFields = null;
+    }
+
+    // Consume pending indices accumulated by @Index decorators
+    if (globalPendingIndices) {
+      meta.indices = globalPendingIndices;
+      globalPendingIndices = null;
+    }
+
+    // Clear pending id
+    globalPendingId = null;
+    globalPendingIdCount = 0;
+
+    collectionMeta.set(target, meta);
+    return target;
+  };
+}
+
+/**
+ * Mark a property as the primary key field.
+ *
+ * Each @PersistedCollection class must have exactly one @Id field.
+ * The field type is inferred from the accompanying @Field decorator,
+ * or defaults to 'string' if @Field is not present.
+ *
+ * @param type - The field type ('string' | 'number' | 'boolean' | 'date'), defaults to 'string'
+ * @param options - Optional configuration (column name override)
+ */
+export function Id(type: FieldType = "string", options?: IdOptions) {
+  return function (_target: undefined, context: unknown): void {
+    const property = extractPropertyName(context);
+    const column = options?.column ?? "id";
+
+    // Track count to detect multiple @Id in same class
+    globalPendingIdCount++;
+    globalPendingId = { property, column, type };
+  };
+}
+
+/**
+ * Mark a property as a persisted field in a collection.
+ *
+ * @param type - The field type ('string' | 'number' | 'boolean' | 'date')
+ * @param options - Optional field configuration (column name override)
+ */
+export function Field(type: FieldType, options?: FieldOptions) {
+  return function (_target: undefined, context: unknown): void {
+    const property = extractPropertyName(context);
+    const column = options?.column ?? toSnakeCase(property);
+
+    // Accumulate field definitions
+    if (!globalPendingFields) {
+      globalPendingFields = new Map();
+    }
+    globalPendingFields.set(property, { column, type });
+  };
+}
+
+/**
+ * Mark column(s) for indexing.
+ *
+ * Can be applied multiple times to create multiple indices.
+ * When applied to a field, indexes that field. Can also specify
+ * composite index columns explicitly.
+ *
+ * @param columns - Optional column names for composite index.
+ *                  If omitted, indexes the decorated field only.
+ *
+ * @example
+ * ```ts
+ * // Single column index on email
+ * @Field('string') @Index() email: string = '';
+ *
+ * // Composite index on [status, created_at]
+ * @Field('string') @Index(['status', 'created_at']) status: string = '';
+ * ```
+ */
+export function Index(columns?: string | string[]) {
+  return function (_target: undefined, context: unknown): void {
+    const property = extractPropertyName(context);
+    const column = toSnakeCase(property);
+
+    // Determine the columns to index
+    let indexColumns: string[];
+    if (columns === undefined) {
+      // Index the decorated field only
+      indexColumns = [column];
+    } else if (typeof columns === "string") {
+      // Single column specified
+      indexColumns = [toSnakeCase(columns)];
+    } else {
+      // Array of columns
+      indexColumns = columns.map(toSnakeCase);
+    }
+
+    // Accumulate index definitions
+    if (!globalPendingIndices) {
+      globalPendingIndices = [];
+    }
+    globalPendingIndices.push({ columns: indexColumns });
+  };
+}

package/src/state/collection/query.ts

@@ -0,0 +1,259 @@
+/**
+ * Query builder for collection WHERE and ORDER BY clauses.
+ *
+ * Produces parameterized SQL to prevent injection attacks.
+ * All values are returned as bind parameters, never interpolated.
+ */
+
+import type { SQLQueryBindings } from "bun:sqlite";
+import type {
+  CollectionMeta,
+  OrderByClause,
+  OrderDirection,
+  WhereClause,
+  WhereCondition,
+  WhereOperator,
+} from "./types";
+
+/**
+ * Result of building a WHERE clause.
+ */
+export interface WhereResult {
+  /** SQL WHERE clause fragment (without 'WHERE' keyword). Empty string if no conditions. */
+  sql: string;
+  /** Bind parameters for the query. */
+  params: SQLQueryBindings[];
+}
+
+/**
+ * Check if a value is a WhereCondition object.
+ */
+function isWhereCondition<T>(value: unknown): value is WhereCondition<T> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "op" in value &&
+    typeof (value as WhereCondition<T>).op === "string"
+  );
+}
+
+/**
+ * Map a property name to its column name using metadata.
+ *
+ * @param meta - Collection metadata
+ * @param property - Property name
+ * @returns Column name
+ * @throws Error if property not found in metadata
+ */
+function getColumn(meta: CollectionMeta, property: string): string {
+  if (property === meta.idProperty) {
+    return meta.idColumn;
+  }
+
+  const field = meta.fields.get(property);
+  if (!field) {
+    throw new Error(
+      `Property "${property}" not found in collection "${meta.table}". ` +
+        `Available fields: ${meta.idProperty}, ${[...meta.fields.keys()].join(", ")}`,
+    );
+  }
+  return field.column;
+}
+
+/**
+ * Build SQL condition fragment and params for a single operator.
+ *
+ * @param column - Column name
+ * @param op - Comparison operator
+ * @param value - Value for comparison
+ * @returns SQL fragment and params tuple
+ */
+function buildOperatorCondition(
+  column: string,
+  op: WhereOperator,
+  value: unknown,
+): { sql: string; params: SQLQueryBindings[] } {
+  switch (op) {
+    case "eq":
+      return { sql: `${column} = ?`, params: [value as SQLQueryBindings] };
+
+    case "neq":
+      return { sql: `${column} != ?`, params: [value as SQLQueryBindings] };
+
+    case "lt":
+      return { sql: `${column} < ?`, params: [value as SQLQueryBindings] };
+
+    case "lte":
+      return { sql: `${column} <= ?`, params: [value as SQLQueryBindings] };
+
+    case "gt":
+      return { sql: `${column} > ?`, params: [value as SQLQueryBindings] };
+
+    case "gte":
+      return { sql: `${column} >= ?`, params: [value as SQLQueryBindings] };
+
+    case "in": {
+      const arr = value as SQLQueryBindings[];
+      if (!Array.isArray(arr) || arr.length === 0) {
+        // Empty IN clause: always false
+        return { sql: "0 = 1", params: [] };
+      }
+      const placeholders = arr.map(() => "?").join(", ");
+      return { sql: `${column} IN (${placeholders})`, params: arr };
+    }
+
+    case "notIn": {
+      const arr = value as SQLQueryBindings[];
+      if (!Array.isArray(arr) || arr.length === 0) {
+        // Empty NOT IN clause: always true (no exclusions)
+        return { sql: "1 = 1", params: [] };
+      }
+      const placeholders = arr.map(() => "?").join(", ");
+      return { sql: `${column} NOT IN (${placeholders})`, params: arr };
+    }
+
+    case "isNull":
+      return { sql: `${column} IS NULL`, params: [] };
+
+    case "isNotNull":
+      return { sql: `${column} IS NOT NULL`, params: [] };
+
+    case "contains":
+      // LIKE '%value%' - escape special LIKE chars
+      return {
+        sql: `${column} LIKE ? ESCAPE '\\'`,
+        params: [`%${escapeLike(String(value))}%`],
+      };
+
+    case "startsWith":
+      // LIKE 'value%'
+      return {
+        sql: `${column} LIKE ? ESCAPE '\\'`,
+        params: [`${escapeLike(String(value))}%`],
+      };
+
+    case "endsWith":
+      // LIKE '%value'
+      return {
+        sql: `${column} LIKE ? ESCAPE '\\'`,
+        params: [`%${escapeLike(String(value))}`],
+      };
+  }
+}
+
+/**
+ * Escape special characters for LIKE patterns.
+ *
+ * SQLite LIKE special chars: % _
+ */
+function escapeLike(value: string): string {
+  return value.replace(/[%_]/g, (char) => `\\${char}`);
+}
+
+/**
+ * Build a WHERE clause from a WhereClause object.
+ *
+ * @param meta - Collection metadata
+ * @param where - Where clause object mapping property names to conditions
+ * @returns WhereResult with SQL fragment and bind parameters
+ *
+ * @example
+ * ```ts
+ * const { sql, params } = buildWhere(meta, {
+ *   status: 'active',
+ *   age: { op: 'gte', value: 18 },
+ * });
+ * // sql: "status = ? AND age >= ?"
+ * // params: ['active', 18]
+ * ```
+ */
+export function buildWhere<T>(
+  meta: CollectionMeta,
+  where: WhereClause<T> | undefined,
+): WhereResult {
+  if (!where || Object.keys(where).length === 0) {
+    return { sql: "", params: [] };
+  }
+
+  const conditions: string[] = [];
+  const params: SQLQueryBindings[] = [];
+
+  for (const [property, whereValue] of Object.entries(where)) {
+    if (whereValue === undefined) {
+      continue;
+    }
+
+    const column = getColumn(meta, property);
+
+    // Determine operator and value
+    let op: WhereOperator;
+    let value: unknown;
+
+    if (isWhereCondition(whereValue)) {
+      op = whereValue.op;
+      value = whereValue.value;
+    } else {
+      // Raw value treated as eq
+      op = "eq";
+      value = whereValue;
+    }
+
+    const result = buildOperatorCondition(column, op, value);
+    conditions.push(result.sql);
+    params.push(...result.params);
+  }
+
+  if (conditions.length === 0) {
+    return { sql: "", params: [] };
+  }
+
+  return {
+    sql: conditions.join(" AND "),
+    params,
+  };
+}
+
+/**
+ * Build an ORDER BY clause from an OrderByClause object.
+ *
+ * @param meta - Collection metadata
+ * @param orderBy - Order by clause object mapping property names to direction
+ * @returns SQL ORDER BY clause (without 'ORDER BY' keyword), empty string if no ordering
+ *
+ * @example
+ * ```ts
+ * const sql = buildOrderBy(meta, { createdAt: 'desc', name: 'asc' });
+ * // "created_at DESC, name ASC"
+ * ```
+ */
+export function buildOrderBy<T>(
+  meta: CollectionMeta,
+  orderBy: OrderByClause<T> | undefined,
+): string {
+  if (!orderBy || Object.keys(orderBy).length === 0) {
+    return "";
+  }
+
+  const clauses: string[] = [];
+
+  for (const [property, direction] of Object.entries(orderBy)) {
+    if (direction === undefined) {
+      continue;
+    }
+
+    const column = getColumn(meta, property);
+    const dir = (direction as OrderDirection).toUpperCase();
+
+    // Validate direction to prevent injection
+    if (dir !== "ASC" && dir !== "DESC") {
+      throw new Error(
+        `Invalid order direction "${direction}" for property "${property}". ` +
+          `Use 'asc' or 'desc'.`,
+      );
+    }
+
+    clauses.push(`${column} ${dir}`);
+  }
+
+  return clauses.join(", ");
+}

package/src/state/collection/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Type definitions for the collection persistence system.
+ *
+ * Collections are multi-row tables with explicit primary keys,
+ * as opposed to singleton @Persisted classes which use a key column.
+ */
+
+/** Supported field types for persistence (same as singleton). */
+export type FieldType = "string" | "number" | "boolean" | "date";
+
+/** Metadata for a single persisted field in a collection. */
+export interface CollectionFieldMeta {
+  /** Property name on the class. */
+  property: string;
+  /** SQLite column name (snake_case). */
+  column: string;
+  /** Field type for serialization. */
+  type: FieldType;
+}
+
+/** Index definition for a collection table. */
+export interface IndexMeta {
+  /** Column names to index (snake_case). */
+  columns: string[];
+}
+
+/** Metadata for a @PersistedCollection class. */
+export interface CollectionMeta {
+  /** SQLite table name. */
+  table: string;
+  /** Property name of the @Id field. */
+  idProperty: string;
+  /** Column name of the @Id field. */
+  idColumn: string;
+  /** Type of the @Id field. */
+  idType: FieldType;
+  /** Map of property name to field metadata (excludes id field). */
+  fields: Map<string, CollectionFieldMeta>;
+  /** Index definitions. */
+  indices: IndexMeta[];
+}
+
+/**
+ * WeakMap storing collection metadata.
+ * Keyed by constructor function, holds CollectionMeta.
+ */
+export const collectionMeta = new WeakMap<object, CollectionMeta>();
+
+// --------------------------------------------------------------------------
+// Query types
+// --------------------------------------------------------------------------
+
+/**
+ * Comparison operators for WHERE clauses.
+ */
+export type WhereOperator =
+  | "eq"
+  | "neq"
+  | "lt"
+  | "lte"
+  | "gt"
+  | "gte"
+  | "in"
+  | "notIn"
+  | "isNull"
+  | "isNotNull"
+  | "contains"
+  | "startsWith"
+  | "endsWith";
+
+/**
+ * A single where condition with explicit operator.
+ */
+export interface WhereCondition<T> {
+  op: WhereOperator;
+  value: T;
+}
+
+/**
+ * A where value can be:
+ * - A raw value (treated as eq)
+ * - A condition object with operator
+ */
+export type WhereValue<T> = T | WhereCondition<T>;
+
+/**
+ * Where clause mapping field names to conditions.
+ * Keys are property names, values are WhereValue.
+ */
+export type WhereClause<T> = {
+  [K in keyof T]?: WhereValue<T[K]>;
+};
+
+/**
+ * Order direction for sorting.
+ */
+export type OrderDirection = "asc" | "desc";
+
+/**
+ * Order by clause - field name to direction.
+ */
+export type OrderByClause<T> = {
+  [K in keyof T]?: OrderDirection;
+};
+
+/**
+ * Options for find() queries.
+ */
+export interface FindOptions<T> {
+  /** Filter conditions. */
+  where?: WhereClause<T>;
+  /** Sort order. */
+  orderBy?: OrderByClause<T>;
+  /** Maximum number of results. */
+  limit?: number;
+  /** Number of results to skip. */
+  offset?: number;
+}
+
+// --------------------------------------------------------------------------
+// CollectionEntity base class
+// --------------------------------------------------------------------------
+
+/**
+ * Abstract base class for collection entities.
+ *
+ * Provides compile-time type safety to distinguish collection entities
+ * from singleton @Persisted classes. Subclasses must be decorated with
+ * @PersistedCollection.
+ *
+ * @example
+ * ```ts
+ * @PersistedCollection('users')
+ * class User extends CollectionEntity {
+ *   @Id() id: string = '';
+ *   @Field('string') name: string = '';
+ *
+ *   async save(): Promise<void> {
+ *     // Implemented by StateLoader binding
+ *   }
+ *
+ *   async delete(): Promise<void> {
+ *     // Implemented by StateLoader binding
+ *   }
+ * }
+ * ```
+ */
+export abstract class CollectionEntity {
+  /**
+   * Persist this entity to the database.
+   * Implemented when the entity is bound to a StateLoader.
+   */
+  abstract save(): Promise<void>;
+
+  /**
+   * Delete this entity from the database.
+   * Implemented when the entity is bound to a StateLoader.
+   */
+  abstract delete(): Promise<void>;
+}

package/src/state/decorators.ts

@@ -25,9 +25,12 @@ import { classMeta, type FieldMeta, type FieldType } from "./types";
 
 /**
  * Convert camelCase to snake_case.
+ * Handles leading uppercase (e.g., 'ID' -> 'id', not '_i_d').
  */
 function toSnakeCase(str: string): string {
-  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+  return str.replace(/[A-Z]/g, (letter, index) =>
+    index === 0 ? letter.toLowerCase() : `_${letter.toLowerCase()}`,
+  );
 }
 
 /** Options for the @Field decorator. */