@shetty4l/core 0.1.33 → 0.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shetty4l/core",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "Shared infrastructure primitives for Bun/TypeScript services",
   "repository": {
     "type": "git",
@@ -18,7 +18,8 @@
     "./daemon": "./src/daemon.ts",
     "./db": "./src/db.ts",
     "./http": "./src/http.ts",
-    "./log": "./src/log.ts"
+    "./log": "./src/log.ts",
+    "./state": "./src/state/index.ts"
   },
   "files": [
     "src/",
@@ -44,6 +45,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@types/bun": "latest",
+    "fast-check": "^4.5.3",
     "husky": "^9.0.0",
     "oxlint": "^1.48.0",
     "typescript": "^5.0.0"

package/src/index.ts

@@ -19,5 +19,6 @@ export type { Err, Ok, Port, Result } from "./result";
 export { err, ok } from "./result";
 export type { ShutdownOpts } from "./signals";
 export { onShutdown } from "./signals";
+export * as state from "./state";
 // Universal primitives — exported directly
 export { readVersion } from "./version";

package/src/state/decorators.ts

@@ -0,0 +1,111 @@
+/**
+ * TC39 decorators for state persistence.
+ *
+ * Uses explicit type specification for all fields to ensure correct
+ * serialization without relying on runtime type inference.
+ *
+ * Note: Bun's TC39 decorator implementation differs from the spec:
+ * - Field decorator context is the field name as a string (not an object)
+ * - Class decorator context is undefined (not an object)
+ * - Field decorators run before class decorator (allows global accumulation)
+ *
+ * @example
+ * ```ts
+ * @Persisted('my_state')
+ * class MyState {
+ *   @Field('string') name: string = '';
+ *   @Field('date') createdAt: Date | null = null;
+ *   @Field('number') count: number = 0;
+ *   @Field('boolean') enabled: boolean = true;
+ * }
+ * ```
+ */
+
+import { classMeta, type FieldMeta, type FieldType } from "./types";
+
+/**
+ * Convert camelCase to snake_case.
+ */
+function toSnakeCase(str: string): string {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+
+/** Options for the @Field decorator. */
+export interface FieldOptions {
+  /** Custom column name. Defaults to snake_case of property name. */
+  column?: string;
+}
+
+type PendingFieldDef = { column: string; type: FieldType };
+type PendingFieldsMap = Map<string, PendingFieldDef>;
+
+// Global accumulator for pending field definitions.
+// In Bun's TC39 implementation, @Field decorators run synchronously
+// before the @Persisted decorator for the same class.
+let globalPendingFields: PendingFieldsMap | null = null;
+
+/**
+ * Mark a class as persisted to a SQLite table.
+ *
+ * @param table - SQLite table name
+ * @throws Error if class extends another @Persisted class
+ */
+export function Persisted(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 @Persisted class
+    let proto = Object.getPrototypeOf(target);
+    while (proto && proto !== Function.prototype) {
+      if (classMeta.has(proto)) {
+        const parentMeta = classMeta.get(proto)!;
+        throw new Error(
+          `@Persisted class "${target.name}" cannot extend @Persisted class "${proto.name}" (table: "${parentMeta.table}"). ` +
+            `State classes do not support inheritance.`,
+        );
+      }
+      proto = Object.getPrototypeOf(proto);
+    }
+
+    // Initialize metadata for this class
+    const meta = { table, fields: new Map<string, FieldMeta>() };
+
+    // 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;
+    }
+
+    classMeta.set(target, meta);
+    return target;
+  };
+}
+
+/**
+ * Mark a property as a persisted field.
+ *
+ * @param type - The field type ('string' | 'number' | 'boolean' | 'date')
+ * @param options - Optional field configuration (column name override)
+ */
+export function Field(type: FieldType, options?: FieldOptions) {
+  // Bun's TC39 decorator: context is the field name as string, not ClassFieldDecoratorContext
+  return function (_target: undefined, context: unknown): void {
+    // In Bun, context is the field name as a string
+    const property = typeof context === "string" ? context : String(context);
+    const column = options?.column ?? toSnakeCase(property);
+
+    // Accumulate field definitions
+    if (!globalPendingFields) {
+      globalPendingFields = new Map();
+    }
+    globalPendingFields.set(property, { column, type });
+  };
+}

package/src/state/index.ts

@@ -0,0 +1,31 @@
+/**
+ * State persistence module.
+ *
+ * Provides decorator-based state persistence with auto-save to SQLite.
+ *
+ * @example
+ * ```ts
+ * import { Persisted, Field, StateLoader } from '@shetty4l/core/state';
+ *
+ * @Persisted('my_state')
+ * class MyState {
+ *   @Field() counter: number = 0;
+ *   @Field({ type: 'date' }) lastUpdated: Date | null = null;
+ * }
+ *
+ * const loader = new StateLoader(db);
+ * const state = loader.load(MyState, 'my-key');
+ * state.counter += 1;  // Auto-saves after 100ms
+ * await loader.flush(); // Force immediate save
+ * ```
+ */
+
+export type { FieldOptions } from "./decorators";
+// Decorators
+export { Field, Persisted } from "./decorators";
+
+// Loader
+export { StateLoader } from "./loader";
+
+// Types
+export type { ClassMeta, FieldMeta, FieldType } from "./types";

package/src/state/loader.ts

@@ -0,0 +1,252 @@
+/**
+ * StateLoader: Load and auto-persist state objects.
+ *
+ * Provides a proxy-based approach to automatically save state changes
+ * to SQLite with debounced writes.
+ */
+
+import type { Database, SQLQueryBindings } from "bun:sqlite";
+import { ensureTable, migrateAdditive } from "./schema";
+import { deserializeValue, serializeValue } from "./serialization";
+import type { ClassMeta } from "./types";
+import { classMeta } from "./types";
+
+/** Debounce delay in milliseconds. */
+const DEBOUNCE_MS = 100;
+
+/**
+ * StateLoader manages loading and persisting state objects.
+ *
+ * @example
+ * ```ts
+ * const loader = new StateLoader(db);
+ * const state = await loader.load(MyState, 'my-key');
+ * state.counter += 1;  // Auto-saves after 100ms
+ * await loader.flush(); // Force immediate save
+ * ```
+ */
+export class StateLoader {
+  private db: Database;
+  private pendingSaves = new Map<string, () => void>();
+  private timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(db: Database) {
+    this.db = db;
+  }
+
+  /**
+   * Check if a state row exists for the given key.
+   *
+   * Unlike `load()`, this does NOT create a row if it doesn't exist.
+   * Ensures table exists and migrates if needed (consistent with load()).
+   *
+   * @param Cls - The @Persisted class constructor
+   * @param key - Unique key to check
+   * @returns `true` if row exists, `false` otherwise
+   * @throws Error if class is not decorated with @Persisted
+   */
+  exists<T extends object>(Cls: new () => T, key: string): boolean {
+    // Get metadata
+    const meta = classMeta.get(Cls);
+    if (!meta || !meta.table) {
+      throw new Error(
+        `Class "${Cls.name}" is not decorated with @Persisted. ` +
+          `Add @Persisted('table_name') to the class.`,
+      );
+    }
+
+    // Ensure table exists and migrate if needed (consistent with load())
+    ensureTable(this.db, meta);
+    migrateAdditive(this.db, meta);
+
+    // Check if row exists
+    const row = this.selectRow(meta, key);
+    return row !== null;
+  }
+
+  /**
+   * Load a state object by key.
+   *
+   * If the row doesn't exist, creates one with default values.
+   * Returns a proxy that auto-saves on property changes.
+   *
+   * @param Cls - The @Persisted class constructor
+   * @param key - Unique key for this state instance
+   * @returns Proxied instance that auto-saves changes
+   * @throws Error if class is not decorated with @Persisted
+   */
+  load<T extends object>(Cls: new () => T, key: string): T {
+    // Get metadata
+    const meta = classMeta.get(Cls);
+    if (!meta || !meta.table) {
+      throw new Error(
+        `Class "${Cls.name}" is not decorated with @Persisted. ` +
+          `Add @Persisted('table_name') to the class.`,
+      );
+    }
+
+    // Ensure table exists and migrate if needed
+    ensureTable(this.db, meta);
+    migrateAdditive(this.db, meta);
+
+    // Create instance to get default values
+    const instance = new Cls();
+
+    // Try to load existing row
+    const row = this.selectRow(meta, key);
+
+    if (row) {
+      // Populate instance from row
+      for (const field of meta.fields.values()) {
+        const rawValue = row[field.column];
+        // If column is NULL (e.g., newly added via migration), keep default value
+        if (rawValue !== null && rawValue !== undefined) {
+          const value = deserializeValue(rawValue, field.type);
+          (instance as Record<string, unknown>)[field.property] = value;
+        }
+      }
+    } else {
+      // Insert default values
+      this.insertRow(meta, key, instance);
+    }
+
+    // Return proxy for auto-save
+    return this.createProxy(instance, meta, key);
+  }
+
+  /**
+   * Flush all pending saves immediately.
+   *
+   * Call this before shutdown to ensure all changes are persisted.
+   */
+  async flush(): Promise<void> {
+    // Cancel all timers
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+
+    // Execute all pending saves
+    for (const save of this.pendingSaves.values()) {
+      save();
+    }
+    this.pendingSaves.clear();
+  }
+
+  private selectRow(
+    meta: ClassMeta,
+    key: string,
+  ): Record<string, unknown> | null {
+    const stmt = this.db.prepare(`SELECT * FROM ${meta.table} WHERE key = ?`);
+    return stmt.get(key) as Record<string, unknown> | null;
+  }
+
+  private insertRow<T extends object>(
+    meta: ClassMeta,
+    key: string,
+    instance: T,
+  ): void {
+    const columns = ["key", "updated_at"];
+    const placeholders = ["?", "datetime('now')"];
+    const values: SQLQueryBindings[] = [key];
+
+    for (const field of meta.fields.values()) {
+      columns.push(field.column);
+      placeholders.push("?");
+      const value = (instance as Record<string, unknown>)[field.property];
+      values.push(serializeValue(value, field.type));
+    }
+
+    const sql = `INSERT INTO ${meta.table} (${columns.join(", ")}) VALUES (${placeholders.join(", ")})`;
+    this.db.prepare(sql).run(...values);
+  }
+
+  private saveRow<T extends object>(
+    meta: ClassMeta,
+    key: string,
+    instance: T,
+  ): void {
+    const setClauses = ["updated_at = datetime('now')"];
+    const values: SQLQueryBindings[] = [];
+
+    for (const field of meta.fields.values()) {
+      setClauses.push(`${field.column} = ?`);
+      const value = (instance as Record<string, unknown>)[field.property];
+      values.push(serializeValue(value, field.type));
+    }
+
+    values.push(key);
+    const sql = `UPDATE ${meta.table} SET ${setClauses.join(", ")} WHERE key = ?`;
+    this.db.prepare(sql).run(...values);
+  }
+
+  private createProxy<T extends object>(
+    instance: T,
+    meta: ClassMeta,
+    key: string,
+  ): T {
+    const saveKey = `${meta.table}:${key}`;
+    const scheduleSave = this.scheduleSave.bind(this);
+    const saveRow = this.saveRow.bind(this);
+
+    return new Proxy(instance, {
+      set(target, prop, value): boolean {
+        // Set the value
+        (target as Record<string | symbol, unknown>)[prop] = value;
+
+        // Only schedule save for @Field properties
+        const propStr = String(prop);
+        if (!meta.fields.has(propStr)) {
+          return true;
+        }
+
+        // Schedule debounced save
+        scheduleSave(saveKey, () => {
+          saveRow(meta, key, target);
+        });
+
+        return true;
+      },
+
+      get(target, prop, receiver): unknown {
+        const value = Reflect.get(target, prop, receiver);
+        // Bind methods to the target
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+
+      ownKeys(target): (string | symbol)[] {
+        return Reflect.ownKeys(target);
+      },
+
+      getOwnPropertyDescriptor(target, prop): PropertyDescriptor | undefined {
+        return Object.getOwnPropertyDescriptor(target, prop);
+      },
+    });
+  }
+
+  private scheduleSave(saveKey: string, saveFn: () => void): void {
+    // Cancel existing timer
+    const existingTimer = this.timers.get(saveKey);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+
+    // Store the save function
+    this.pendingSaves.set(saveKey, saveFn);
+
+    // Schedule new timer
+    const timer = setTimeout(() => {
+      this.timers.delete(saveKey);
+      const fn = this.pendingSaves.get(saveKey);
+      if (fn) {
+        fn();
+        this.pendingSaves.delete(saveKey);
+      }
+    }, DEBOUNCE_MS);
+
+    this.timers.set(saveKey, timer);
+  }
+}

package/src/state/schema.ts

@@ -0,0 +1,69 @@
+/**
+ * Schema management for SQLite persistence.
+ *
+ * Handles table creation and additive schema migrations.
+ */
+
+import type { Database } from "bun:sqlite";
+import { sqliteType } from "./serialization";
+import type { ClassMeta } from "./types";
+
+/**
+ * Ensure a table exists for the given class metadata.
+ *
+ * Creates a table with:
+ * - `key` TEXT PRIMARY KEY
+ * - One column per @Field (snake_case names)
+ * - `updated_at` TEXT for tracking modifications
+ *
+ * @param db - SQLite database instance
+ * @param meta - Class metadata from @Persisted/@Field decorators
+ */
+export function ensureTable(db: Database, meta: ClassMeta): void {
+  const columns: string[] = ["key TEXT PRIMARY KEY"];
+
+  for (const field of meta.fields.values()) {
+    const sqlType = sqliteType(field.type);
+    columns.push(`${field.column} ${sqlType}`);
+  }
+
+  columns.push("updated_at TEXT");
+
+  const sql = `CREATE TABLE IF NOT EXISTS ${meta.table} (${columns.join(", ")})`;
+  db.exec(sql);
+}
+
+/**
+ * Perform additive migration: add any missing columns.
+ *
+ * This function:
+ * - Reads existing columns via PRAGMA table_info
+ * - Adds columns for any @Field not yet in the table
+ * - Never drops or modifies existing columns
+ * - Is idempotent (safe to call multiple times)
+ *
+ * @param db - SQLite database instance
+ * @param meta - Class metadata from @Persisted/@Field decorators
+ */
+export function migrateAdditive(db: Database, meta: ClassMeta): void {
+  // Get existing columns
+  const info = db.prepare(`PRAGMA table_info(${meta.table})`).all() as {
+    name: string;
+  }[];
+  const existingColumns = new Set(info.map((row) => row.name));
+
+  // Add missing columns
+  for (const field of meta.fields.values()) {
+    if (!existingColumns.has(field.column)) {
+      const sqlType = sqliteType(field.type);
+      db.exec(
+        `ALTER TABLE ${meta.table} ADD COLUMN ${field.column} ${sqlType}`,
+      );
+    }
+  }
+
+  // Ensure updated_at exists
+  if (!existingColumns.has("updated_at")) {
+    db.exec(`ALTER TABLE ${meta.table} ADD COLUMN updated_at TEXT`);
+  }
+}

package/src/state/serialization.ts

@@ -0,0 +1,103 @@
+/**
+ * Serialization utilities for SQLite persistence.
+ *
+ * Handles conversion between JavaScript types and SQLite-compatible values.
+ */
+
+import type { FieldType } from "./types";
+
+/** SQLite column type. */
+export type SqliteType = "TEXT" | "REAL" | "INTEGER";
+
+/**
+ * Serialize a JavaScript value for SQLite storage.
+ *
+ * @param value - The value to serialize
+ * @param type - The field type
+ * @returns SQLite-compatible value
+ * @throws Error if value is NaN or Infinity
+ */
+export function serializeValue(
+  value: unknown,
+  type: FieldType,
+): string | number | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  switch (type) {
+    case "string":
+      return String(value);
+
+    case "number": {
+      const num = value as number;
+      if (Number.isNaN(num)) {
+        throw new Error(
+          "Cannot serialize NaN to SQLite. Ensure the value is a valid number.",
+        );
+      }
+      if (!Number.isFinite(num)) {
+        throw new Error(
+          "Cannot serialize Infinity to SQLite. Ensure the value is a finite number.",
+        );
+      }
+      return num;
+    }
+
+    case "boolean":
+      return value ? 1 : 0;
+
+    case "date":
+      return (value as Date).toISOString();
+  }
+}
+
+/**
+ * Deserialize a SQLite value to a JavaScript type.
+ *
+ * @param value - The SQLite value
+ * @param type - The field type
+ * @returns Deserialized JavaScript value
+ */
+export function deserializeValue(
+  value: unknown,
+  type: FieldType,
+): string | number | boolean | Date | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  switch (type) {
+    case "string":
+      return String(value);
+
+    case "number":
+      return Number(value);
+
+    case "boolean":
+      return value === 1 || value === true;
+
+    case "date":
+      return new Date(value as string);
+  }
+}
+
+/**
+ * Get the SQLite column type for a field type.
+ *
+ * @param type - The field type
+ * @returns SQLite column type
+ */
+export function sqliteType(type: FieldType): SqliteType {
+  switch (type) {
+    case "string":
+    case "date":
+      return "TEXT";
+
+    case "number":
+      return "REAL";
+
+    case "boolean":
+      return "INTEGER";
+  }
+}

package/src/state/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Type definitions for the state persistence system.
+ */
+
+/** Supported field types for persistence. */
+export type FieldType = "string" | "number" | "boolean" | "date";
+
+/** Metadata for a single persisted field. */
+export interface FieldMeta {
+  /** Property name on the class. */
+  property: string;
+  /** SQLite column name (snake_case). */
+  column: string;
+  /** Field type for serialization. */
+  type: FieldType;
+}
+
+/** Metadata for a persisted class. */
+export interface ClassMeta {
+  /** SQLite table name. */
+  table: string;
+  /** Map of property name to field metadata. */
+  fields: Map<string, FieldMeta>;
+}
+
+/**
+ * WeakMap storing class metadata.
+ * Keyed by constructor function, holds ClassMeta.
+ */
+export const classMeta = new WeakMap<object, ClassMeta>();