json-database-st 2.0.3 → 3.1.4

package/JSONDatabase.d.ts

@@ -1,200 +1,87 @@
-// File: JSONDatabase.d.ts
 import { EventEmitter } from 'events';
 
-/**
- * A lightweight schema representation accepted by the DB.
- * Libraries such as Zod or Joi can be used at runtime; this type is intentionally permissive.
- */
-export type SchemaLike = any;
-
-/**
- * Options configuring behavior of the JSONDatabase.
- */
-export interface DBOptions {
-    /**
-     * Optional key used to encrypt the file on disk. If provided,
-     * all reads/writes will transparently encrypt/decrypt data.
-     */
-    encryptionKey?: string;
-
-    /**
-     * When true the file will be written with 2-space indentation for readability.
-     * Defaults to false (compact).
-     */
-    prettyPrint?: boolean;
+export interface IndexConfig {
+  name: string;
+  path: string;
+  field: string;
+  unique?: boolean;
+}
 
-    /**
-     * When true, any change is flushed to disk immediately. When false,
-     * writes may be batched for performance.
-     * Defaults to true.
-     */
-    writeOnChange?: boolean;
+export interface DatabaseOptions {
+  encryptionKey?: string;
+  saveDelay?: number;
+  prettyPrint?: boolean;
+  silent?: boolean;
+  wal?: boolean;
+  schema?: any;
+  indices?: IndexConfig[];
+}
 
-    /**
-     * Optional validation schema (Zod/Joi/etc). If provided, writes
-     * that would violate the schema will be rejected.
-     */
-    schema?: SchemaLike;
+export interface MiddlewareContext {
+  path: string;
+  value?: any;
+  finalData?: any;
+  [key: string]: any;
+}
 
-    /**
-     * Optional index definitions for faster lookups via `findByIndex`.
-     */
-    indices?: IndexDefinition[];
+export type MiddlewareFn = (ctx: MiddlewareContext) => MiddlewareContext;
 
-    /**
-     * If true, database will periodically compact the file to reduce size.
-     */
-    autoCompact?: boolean;
+export class DBError extends Error {}
+export class TransactionError extends DBError {}
+export class ValidationError extends DBError {
+  issues?: any[];
+  constructor(msg: string, issues?: any[]);
 }
 
-/**
- * Defines a secondary index on objects stored under a path.
- * - `path` is a dot-separated path inside the DB where the array/object lives.
- * - `field` is the property name to index on each element.
- */
-export interface IndexDefinition {
-    name: string;
-    path: string;
-    field: string;
-    unique?: boolean;
+export class QueryCursor implements PromiseLike<any[]> {
+  limit(n: number): this;
+  skip(n: number): this;
+  sort(criteria: any): this;
+  select(fields: string[]): this;
+  exec(): Promise<any[]>;
+  then<TResult1 = any[], TResult2 = never>(
+    onfulfilled?: ((value: any[]) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  ): PromiseLike<TResult1 | TResult2>;
 }
 
-/**
- * Discriminated union describing a single batched operation.
- */
-export type BatchOp =
-    | { type: 'set'; path: string; value: any }
-    | { type: 'delete'; path: string }
-    | { type: 'push'; path: string; values: any[] }
-    | { type: 'pull'; path: string; values: any[] };
-
-/**
- * Main JSON file-backed database.
- *
- * The API is promise-based and supports paths using dot-notation
- * to address nested objects/arrays (e.g. "users.0.name").
- */
 export default class JSONDatabase extends EventEmitter {
-    /**
-     * Open or create a database file at `filename`.
-     * @param filename Path to JSON file on disk.
-     * @param options Optional DBOptions to configure behavior.
-     */
-    constructor(filename: string, options?: DBOptions);
-
-    /**
-     * Read a value at `path`. If `path` is omitted, returns the entire DB.
-     * @param path Dot-separated path or undefined for root.
-     * @param defaultValue Value returned when the path is missing.
-     */
-    get<T = any>(path?: string, defaultValue?: T): Promise<T>;
-
-    /**
-     * Return true if the given path exists.
-     */
-    has(path: string): Promise<boolean>;
-
-    /**
-     * Set the value at `path`. If `path` points to a nested location,
-     * intermediate objects/arrays will be created as needed.
-     */
-    set(path: string, value: any): Promise<any>;
-
-    /**
-     * Delete the value at `path`. Returns true if something was deleted.
-     */
-    delete(path: string): Promise<boolean>;
-
-    /**
-     * Append one or more items to an array at `path`. If the target is missing,
-     * an array will be created.
-     */
-    push(path: string, ...items: any[]): Promise<void>;
-
-    /**
-     * Remove one or more items from an array at `path` (strict equality).
-     */
-    pull(path: string, ...items: any[]): Promise<void>;
-
-    /**
-     * Atomically add `amount` to a numeric value at `path`. If the value is missing,
-     * it will be treated as 0 before adding.
-     */
-    add(path: string, amount: number): Promise<number>;
-
-    /**
-     * Atomically subtract `amount` from a numeric value at `path`.
-     */
-    subtract(path: string, amount: number): Promise<number>;
-
-    /**
-     * Run a function with the current DB snapshot and atomically persist
-     * the result. The function may mutate the provided object (in-memory)
-     * and the final value will be written back.
-     */
-    transaction<T = any>(fn: (data: any) => T | Promise<T>): Promise<T>;
-
-    /**
-     * Execute a batch of operations. If `stopOnError` is true, processing
-     * will stop at the first failing operation and the returned promise will reject.
-     */
-    batch(ops: BatchOp[], options?: { stopOnError?: boolean }): Promise<any>;
-
-    /**
-     * Find the first item under `path` that matches `predicate`.
-     * `predicate` may be an object of key/value pairs or a predicate function.
-     */
-    find<T = any>(path: string, predicate: Partial<T> | ((item: T) => boolean)): Promise<T | undefined>;
-
-    /**
-     * Lookup a record using a previously defined index.
-     */
-    findByIndex<T = any>(indexName: string, value: any): Promise<T | undefined>;
-
-    /**
-     * Return a paginated slice of an array at `path`. `page` is 1-based.
-     */
-    paginate<T = any>(
-        path: string,
-        page?: number,
-        limit?: number,
-        filterFn?: (item: T) => boolean
-    ): Promise<{
-        data: T[];
-        meta: { total: number; page: number; limit: number; totalPages: number; hasNext: boolean };
-    }>;
-
-    /**
-     * Create a snapshot file (or internal snapshot) and return the snapshot id/path.
-     */
-    createSnapshot(label?: string): Promise<string>;
-
-    /**
-     * Remove all data and return the previous root object.
-     */
-    clear(): Promise<object>;
-
-    /**
-     * Close any open file handles and stop background tasks.
-     */
-    close(): Promise<void>;
-
-    /**
-     * Register a handler to run before an operation. `op` is one of: 'get','set','delete','push','pull','batch'.
-     * The callback receives a context object with details about the operation and may throw to abort the operation.
-     */
-    before(op: string, path: string, cb: (ctx: any) => any): void;
-
-    /**
-     * Register a handler to run after an operation completes successfully.
-     */
-    after(op: string, path: string, cb: (ctx: any) => any): void;
+  static DBError: typeof DBError;
+  static TransactionError: typeof TransactionError;
+  static ValidationError: typeof ValidationError;
+  static QueryCursor: typeof QueryCursor;
+
+  constructor(filename: string, options?: DatabaseOptions);
+  
+  get<T = any>(path?: string, defaultValue?: T): Promise<T>;
+  has(path: string): Promise<boolean>;
+  set(path: string, value: any): Promise<boolean>;
+  delete(path: string): Promise<boolean>;
+  
+  push(path: string, ...items: any[]): Promise<boolean | void>;
+  pull(path: string, ...items: any[]): Promise<boolean | void>;
+  
+  add(path: string, amount: number): Promise<boolean>;
+  subtract(path: string, amount: number): Promise<boolean>;
+  
+  find<T = any>(path: string, predicate: ((item: T) => boolean) | object): Promise<T | undefined>;
+  findByIndex<T = any>(indexName: string, value: any): Promise<T | undefined>;
+  
+  query(path: string, query?: any): QueryCursor;
+  
+  transaction<T = any>(fn: (data: any) => T | Promise<T>): Promise<boolean>;
+  batch(ops: Array<{ type: 'set' | 'delete' | 'push'; path: string; value?: any; values?: any[] }>): Promise<boolean>;
+  
+  clear(): Promise<boolean>;
+  
+  paginate<T = any>(path: string, page?: number, limit?: number): Promise<{
+    data: T[];
+    meta: { total: number; page: number; limit: number; totalPages: number; hasNext: boolean };
+  }>;
+  
+  createSnapshot(label?: string): Promise<string>;
+  close(): Promise<void>;
+
+  before(op: 'set' | 'delete' | 'push' | 'pull', pattern: string, cb: MiddlewareFn): void;
+  after(op: 'set' | 'delete' | 'push' | 'pull', pattern: string, cb: MiddlewareFn): void;
 }
-
-/* Example usage:
-import JSONDatabase from './JSONDatabase';
-
-const db = new JSONDatabase('data.json', { prettyPrint: true });
-await db.set('users.alice', { id: 'alice', age: 30 });
-const alice = await db.get('users.alice');
-*/