@warlock.js/core 4.0.48 → 4.0.59

package/esm/repositories/contracts/query-builder.contract.d.ts

@@ -0,0 +1,279 @@
+import type { ChunkCallback, CursorPaginationOptions, CursorPaginationResult, FilterOptions, FilterRules, PaginationResult, WhereOperator } from "./types";
+/**
+ * Query builder contract for building database queries
+ * This interface is ORM-agnostic and can be implemented by any data source adapter
+ *
+ * @template T - The type of records being queried
+ */
+export interface QueryBuilderContract<T> {
+    /**
+     * Add a where clause to the query
+     *
+     * @param field - Column name
+     * @param value - Value to compare
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.where("email", "user@example.com")
+     */
+    where(field: string, value: any): this;
+    /**
+     * Add a where clause with operator
+     *
+     * @param field - Column name
+     * @param operator - Comparison operator
+     * @param value - Value to compare
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.where("age", ">", 18)
+     */
+    where(field: string, operator: WhereOperator, value: any): this;
+    /**
+     * Add multiple where clauses from object
+     *
+     * @param conditions - Object mapping columns to values
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.where({ email: "user@example.com", isActive: true })
+     */
+    where(conditions: Record<string, any>): this;
+    /**
+     * Add a where clause using callback
+     *
+     * @param callback - Function that receives query builder
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.where(q => q.where("age", ">", 18).orWhere("role", "admin"))
+     */
+    where(callback: (query: this) => void): this;
+    /**
+     * Add an OR where clause
+     *
+     * @param field - Column name
+     * @param value - Value to compare
+     * @returns Query builder for chaining
+     */
+    orWhere(field: string, value: any): this;
+    /**
+     * Add an OR where clause with operator
+     *
+     * @param field - Column name
+     * @param operator - Comparison operator
+     * @param value - Value to compare
+     * @returns Query builder for chaining
+     */
+    orWhere(field: string, operator: WhereOperator, value: any): this;
+    /**
+     * Add an OR where clause from object
+     *
+     * @param conditions - Object mapping columns to values
+     * @returns Query builder for chaining
+     */
+    orWhere(conditions: Record<string, any>): this;
+    /**
+     * Add a WHERE IN clause
+     *
+     * @param field - Column name
+     * @param values - Array of values
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.whereIn("id", [1, 2, 3])
+     */
+    whereIn(field: string, values: any[]): this;
+    /**
+     * Add a WHERE NOT IN clause
+     *
+     * @param field - Column name
+     * @param values - Array of values
+     * @returns Query builder for chaining
+     */
+    whereNotIn(field: string, values: any[]): this;
+    /**
+     * Add a WHERE NULL clause
+     *
+     * @param field - Column name
+     * @returns Query builder for chaining
+     */
+    whereNull(field: string): this;
+    /**
+     * Add a WHERE NOT NULL clause
+     *
+     * @param field - Column name
+     * @returns Query builder for chaining
+     */
+    whereNotNull(field: string): this;
+    /**
+     * Add a WHERE BETWEEN clause
+     *
+     * @param field - Column name
+     * @param range - Tuple of [min, max] values
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.whereBetween("age", [18, 65])
+     */
+    whereBetween(field: string, range: [any, any]): this;
+    /**
+     * Add a WHERE LIKE clause
+     *
+     * @param field - Column name
+     * @param pattern - Pattern to match
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.whereLike("email", "%@example.com")
+     */
+    whereLike(field: string, pattern: string): this;
+    /**
+     * Pretty print the query
+     */
+    pretty(): string;
+    /**
+     * Select specific columns
+     *
+     * @param fields - Array of column names
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.select(["id", "name", "email"])
+     */
+    select(fields: string[]): this;
+    /**
+     * Select specific columns (variadic)
+     *
+     * @param fields - Column names as arguments
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.select("id", "name", "email")
+     */
+    select(...fields: string[]): this;
+    /**
+     * Deselect specific columns
+     *
+     * @param fields - Array of column names to exclude
+     * @returns Query builder for chaining
+     */
+    deselect(fields: string[]): this;
+    /**
+     * Deselect specific columns (variadic)
+     *
+     * @param fields - Column names to exclude as arguments
+     * @returns Query builder for chaining
+     */
+    deselect(...fields: string[]): this;
+    /**
+     * Order results by column
+     *
+     * @param field - Column name
+     * @param direction - Sort direction (default: "asc")
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.orderBy("createdAt", "desc")
+     */
+    orderBy(field: string, direction?: "asc" | "desc"): this;
+    /**
+     * Order results using object mapping
+     *
+     * @param orderBy - Object mapping columns to directions
+     * @returns Query builder for chaining
+     *
+     * @example
+     * query.sortBy({ createdAt: "desc", name: "asc" })
+     */
+    sortBy(orderBy: Record<string, "asc" | "desc">): this;
+    /**
+     * Order results randomly
+     *
+     * @param limit - Optional limit for random selection
+     * @returns Query builder for chaining
+     */
+    random(limit?: number): this;
+    /**
+     * Limit number of results
+     *
+     * @param limit - Maximum number of records
+     * @returns Query builder for chaining
+     */
+    limit(limit: number): this;
+    /**
+     * Skip a number of results
+     *
+     * @param offset - Number of records to skip
+     * @returns Query builder for chaining
+     */
+    offset(offset: number): this;
+    /**
+     * Alias for offset
+     *
+     * @param count - Number of records to skip
+     * @returns Query builder for chaining
+     */
+    skip(count: number): this;
+    /**
+     * Apply repository filters to query
+     *
+     * @param filters - Filter structure definition
+     * @param data - Data containing filter values
+     * @param options - Filter options (date formats, etc.)
+     * @returns Query builder for chaining
+     */
+    applyFilters(filters: FilterRules<this>, data: any, options: FilterOptions): this;
+    /**
+     * Execute query and get all results
+     *
+     * @returns Promise resolving to array of records
+     */
+    get(): Promise<T[]>;
+    /**
+     * Execute query and get first result
+     *
+     * @returns Promise resolving to first record or null
+     */
+    first(): Promise<T | null>;
+    /**
+     * Count total matching records
+     *
+     * @returns Promise resolving to count
+     */
+    count(): Promise<number>;
+    /**
+     * Execute query with pagination
+     *
+     * @param page - Page number (1-indexed)
+     * @param limit - Items per page
+     * @returns Promise resolving to pagination result
+     */
+    paginate(page: number, limit: number): Promise<PaginationResult<T>>;
+    /**
+     * Execute query with cursor-based pagination
+     * More efficient for large datasets as it doesn't require counting total records
+     *
+     * @param options - Cursor pagination options
+     * @returns Promise resolving to cursor pagination result
+     *
+     * @example
+     * const result = await query.cursorPaginate({ limit: 10, cursor: lastId });
+     */
+    cursorPaginate(options: CursorPaginationOptions): Promise<CursorPaginationResult<T>>;
+    /**
+     * Process results in chunks
+     *
+     * @param size - Chunk size
+     * @param callback - Function called for each chunk
+     * @returns Promise that resolves when chunking is complete
+     */
+    chunk(size: number, callback: ChunkCallback<T>): Promise<void>;
+    /**
+     * Clone the query builder
+     *
+     * @returns New query builder instance with same state
+     */
+    clone(): this;
+}
+//# sourceMappingURL=query-builder.contract.d.ts.map

package/esm/repositories/contracts/query-builder.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder.contract.d.ts","sourceRoot":"","sources":["../../../src/repositories/contracts/query-builder.contract.ts"],"names":[],"mappings":"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"}

package/esm/repositories/contracts/repository-adapter.contract.d.ts

@@ -0,0 +1,183 @@
+import type { QueryBuilderContract } from "./query-builder.contract";
+import type { ChunkCallback, CursorPaginationOptions, CursorPaginationResult, PaginationResult } from "./types";
+/**
+ * Repository adapter contract for data source operations
+ * This interface abstracts database/ORM operations and can be implemented
+ * for any data source (Cascade, Prisma, Drizzle, etc.)
+ *
+ * @template T - The type of records managed by this adapter
+ */
+export interface RepositoryAdapterContract<T> {
+    /**
+     * Create a new query builder instance
+     *
+     * @returns Query builder for constructing queries
+     *
+     * @example
+     * const query = adapter.query();
+     * const users = await query.where("isActive", true).get();
+     */
+    query(): QueryBuilderContract<T>;
+    /**
+     * Register events
+     *
+     * @returns Array of event callbacks
+     */
+    registerEvents(eventsCallback: any): any[];
+    /**
+     * Resolve the repository name
+     *
+     * @returns The repository name
+     */
+    resolveRepositoryName(): string;
+    /**
+     * Serialize the given model for caching
+     *
+     * @param model - The model to serialize
+     * @returns The serialized data
+     */
+    serializeModel(model: T): any;
+    /**
+     * Deserialize the given data
+     *
+     * @param data - The data to deserialize
+     * @returns The deserialized model
+     */
+    deserializeModel(data: any): T;
+    /**
+     * Find a record by its ID
+     *
+     * @param id - Record identifier
+     * @returns Promise resolving to record or null if not found
+     *
+     * @example
+     * const user = await adapter.find(1);
+     */
+    find(id: any): Promise<T | null>;
+    /**
+     * Find a record by column value
+     *
+     * @param column - Column name
+     * @param value - Value to search for
+     * @returns Promise resolving to record or null if not found
+     *
+     * @example
+     * const user = await adapter.findBy("email", "user@example.com");
+     */
+    findBy(column: string, value: any): Promise<T | null>;
+    /**
+     * Create a new record
+     *
+     * @param data - Record data
+     * @returns Promise resolving to created record
+     *
+     * @example
+     * const user = await adapter.create({ name: "John", email: "john@example.com" });
+     */
+    create(data: any): Promise<T>;
+    /**
+     * Update a record by ID
+     *
+     * @param id - Record identifier
+     * @param data - Updated data
+     * @returns Promise resolving to updated record
+     *
+     * @example
+     * const user = await adapter.update(1, { name: "Jane" });
+     */
+    update(id: any, data: any): Promise<T>;
+    /**
+     * Delete a record by ID
+     *
+     * @param id - Record identifier
+     * @returns Promise that resolves when deletion is complete
+     *
+     * @example
+     * await adapter.delete(1);
+     */
+    delete(id: any): Promise<void>;
+    /**
+     * Update multiple records matching filter
+     *
+     * @param filter - Filter criteria
+     * @param data - Updated data
+     * @returns Promise resolving to number of updated records
+     *
+     * @example
+     * const count = await adapter.updateMany({ isActive: false }, { deletedAt: new Date() });
+     */
+    updateMany(filter: any, data: any): Promise<number>;
+    /**
+     * Delete multiple records matching filter
+     *
+     * @param filter - Filter criteria
+     * @returns Promise resolving to number of deleted records
+     *
+     * @example
+     * const count = await adapter.deleteMany({ isActive: false });
+     */
+    deleteMany(filter: any): Promise<number>;
+    /**
+     * Count records matching optional filter
+     *
+     * @param filter - Optional filter criteria
+     * @returns Promise resolving to count
+     *
+     * @example
+     * const total = await adapter.count();
+     * const active = await adapter.count({ isActive: true });
+     */
+    count(filter?: any): Promise<number>;
+    /**
+     * Get paginated results
+     *
+     * @param page - Page number (1-indexed)
+     * @param limit - Items per page
+     * @returns Promise resolving to pagination result
+     *
+     * @example
+     * const result = await adapter.paginate(1, 10);
+     * console.log(result.documents); // Array of records
+     * console.log(result.pagination); // { page, limit, total, pages, result }
+     */
+    paginate(page: number, limit: number): Promise<PaginationResult<T>>;
+    /**
+     * Get cursor-paginated results
+     * More efficient for large datasets as it doesn't require counting total records
+     *
+     * @param options - Cursor pagination options
+     * @returns Promise resolving to cursor pagination result
+     *
+     * @example
+     * const result = await adapter.cursorPaginate({ limit: 10, cursor: lastId });
+     * console.log(result.documents); // Array of records
+     * console.log(result.pagination); // { limit, result, hasMore, nextCursor, prevCursor }
+     */
+    cursorPaginate(options: CursorPaginationOptions): Promise<CursorPaginationResult<T>>;
+    /**
+     * Process records in chunks
+     *
+     * @param size - Chunk size
+     * @param callback - Function called for each chunk
+     * @returns Promise that resolves when chunking is complete
+     *
+     * @example
+     * await adapter.chunk(100, async (records, info) => {
+     *   await processRecords(records);
+     *   // Return false to stop chunking
+     * });
+     */
+    chunk(size: number, callback: ChunkCallback<T>): Promise<void>;
+    /**
+     * Create a model instance from data
+     * This is used by repositories to instantiate models from cached or raw data
+     *
+     * @param data - Raw data
+     * @returns Model instance
+     *
+     * @example
+     * const user = adapter.createModel({ id: 1, name: "John" });
+     */
+    createModel(data: any): T;
+}
+//# sourceMappingURL=repository-adapter.contract.d.ts.map

package/esm/repositories/contracts/repository-adapter.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-adapter.contract.d.ts","sourceRoot":"","sources":["../../../src/repositories/contracts/repository-adapter.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EACV,aAAa,EACb,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAK1C;;;;;;;;OAQG;IACH,KAAK,IAAI,oBAAoB,CAAC,CAAC,CAAC,CAAC;IAEjC;;;;OAIG;IACH,cAAc,CAAC,cAAc,EAAE,GAAG,GAAG,GAAG,EAAE,CAAC;IAE3C;;;;OAIG;IACH,qBAAqB,IAAI,MAAM,CAAC;IAEhC;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC;IAE9B;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC;IAM/B;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEjC;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEtD;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE9B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEvC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAM/B;;;;;;;;;OASG;IACH,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpD;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAMzC;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAMrC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpE;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;IAMrF;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAM/D;;;;;;;;;OASG;IACH,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC;CAC3B"}