@dotdo/do 0.1.0

package/dist/db/collections/base.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Base Collection - Generic CRUD operations for DO collections
+ *
+ * @module collections/base
+ *
+ * @description
+ * Provides the foundational collection interface that all specialized collections
+ * extend. Uses Durable Object SQLite storage for persistence.
+ *
+ * @example
+ * ```typescript
+ * class CustomerCollection extends BaseCollection<Customer> {
+ *   constructor(ctx: DurableObjectState) {
+ *     super(ctx, 'customers', 'cust')
+ *   }
+ * }
+ *
+ * const customers = new CustomerCollection(ctx)
+ * const customer = await customers.create({ name: 'Acme' })
+ * ```
+ */
+import type { CollectionMethods, ListOptions, ListResult, FilterExpression, FilterOp } from '../../types/collections';
+/**
+ * Storage interface for Durable Object state
+ *
+ * @description
+ * Abstracts the DO storage layer to enable testing with mocks.
+ * In production, this wraps ctx.storage from Cloudflare Workers.
+ */
+export interface DOStorage {
+    /**
+     * Execute a SQL query against the DO SQLite database
+     *
+     * @param query - SQL query string with ? placeholders
+     * @param params - Parameter values for placeholders
+     * @returns Query results
+     */
+    sql<T = unknown>(query: string, ...params: unknown[]): Promise<T[]>;
+    /**
+     * Get a value by key from the storage
+     *
+     * @param key - Storage key
+     * @returns The stored value or undefined
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Store a value by key
+     *
+     * @param key - Storage key
+     * @param value - Value to store
+     */
+    put<T = unknown>(key: string, value: T): Promise<void>;
+    /**
+     * Delete a value by key
+     *
+     * @param key - Storage key
+     * @returns True if the key existed
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * List keys with optional prefix filtering
+     *
+     * @param options - List options including prefix and limit
+     * @returns Map of key-value pairs
+     */
+    list<T = unknown>(options?: {
+        prefix?: string;
+        limit?: number;
+    }): Promise<Map<string, T>>;
+}
+/**
+ * Configuration options for BaseCollection
+ */
+export interface CollectionConfig {
+    /**
+     * Name of the collection (used as table name)
+     */
+    name: string;
+    /**
+     * Prefix for generated IDs (e.g., 'cust' -> 'cust_abc123')
+     */
+    idPrefix: string;
+    /**
+     * Default page size for list operations
+     * @default 50
+     */
+    defaultLimit?: number;
+    /**
+     * Maximum page size allowed
+     * @default 1000
+     */
+    maxLimit?: number;
+}
+/**
+ * Base collection class providing generic CRUD operations
+ *
+ * @description
+ * All DO collections extend this class to inherit standard CRUD operations,
+ * filtering, pagination, and storage abstraction. The class is generic over
+ * the entity type T, which must have an 'id' field.
+ *
+ * @typeParam T - Entity type with required 'id' field
+ *
+ * @example
+ * ```typescript
+ * interface Product {
+ *   id: string
+ *   name: string
+ *   price: number
+ *   createdAt: number
+ *   updatedAt: number
+ * }
+ *
+ * class ProductCollection extends BaseCollection<Product> {
+ *   constructor(storage: DOStorage) {
+ *     super(storage, { name: 'products', idPrefix: 'prod' })
+ *   }
+ *
+ *   // Add domain-specific methods
+ *   async findByPriceRange(min: number, max: number): Promise<Product[]> {
+ *     return this.find({
+ *       and: [
+ *         { field: 'price', op: 'gte', value: min },
+ *         { field: 'price', op: 'lte', value: max }
+ *       ]
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseCollection<T extends {
+    id: string;
+}> implements CollectionMethods<T> {
+    /**
+     * DO storage interface
+     */
+    protected readonly storage: DOStorage;
+    /**
+     * Collection configuration
+     */
+    protected readonly config: Required<CollectionConfig>;
+    /**
+     * Create a new BaseCollection instance
+     *
+     * @param storage - DO storage interface
+     * @param config - Collection configuration
+     */
+    constructor(storage: DOStorage, config: CollectionConfig);
+    /**
+     * Generate a unique ID for a new entity
+     *
+     * @returns A unique ID in format '{prefix}_{nanoid}'
+     *
+     * @example
+     * ```typescript
+     * const id = this.generateId() // 'cust_V1StGXR8_Z5jdHi6B-myT'
+     * ```
+     */
+    protected generateId(): string;
+    /**
+     * Get current timestamp in Unix milliseconds
+     *
+     * @returns Current time as Unix timestamp (ms)
+     */
+    protected now(): number;
+    /**
+     * Initialize the collection's database table if it doesn't exist
+     *
+     * @description
+     * Called automatically on first access. Creates the SQLite table
+     * with appropriate schema for the entity type.
+     */
+    protected abstract initializeTable(): Promise<void>;
+    /**
+     * List entities with pagination and filtering
+     *
+     * @param options - List options including limit, offset, cursor, ordering, and filter
+     * @returns Paginated list result with items and metadata
+     *
+     * @example
+     * ```typescript
+     * // Simple pagination
+     * const page1 = await collection.list({ limit: 10 })
+     * const page2 = await collection.list({ limit: 10, cursor: page1.cursor })
+     *
+     * // With filtering
+     * const active = await collection.list({
+     *   filter: { field: 'status', op: 'eq', value: 'active' },
+     *   orderBy: 'createdAt',
+     *   orderDir: 'desc'
+     * })
+     * ```
+     */
+    list(options?: ListOptions): Promise<ListResult<T>>;
+    /**
+     * Get a single entity by ID
+     *
+     * @param id - Entity ID
+     * @returns The entity or null if not found
+     *
+     * @example
+     * ```typescript
+     * const customer = await customers.get('cust_abc123')
+     * if (customer) {
+     *   console.log(customer.name)
+     * }
+     * ```
+     */
+    get(id: string): Promise<T | null>;
+    /**
+     * Create a new entity
+     *
+     * @param data - Entity data without ID (ID is auto-generated)
+     * @returns The created entity with generated ID and timestamps
+     *
+     * @throws {Error} If creation fails due to validation or storage error
+     *
+     * @example
+     * ```typescript
+     * const customer = await customers.create({
+     *   name: 'Acme Corp',
+     *   email: 'contact@acme.com'
+     * })
+     * console.log(customer.id) // 'cust_abc123'
+     * ```
+     */
+    create(data: Omit<T, 'id'>): Promise<T>;
+    /**
+     * Update an existing entity
+     *
+     * @param id - Entity ID
+     * @param data - Partial entity data to merge
+     * @returns The updated entity
+     *
+     * @throws {Error} If entity not found or update fails
+     *
+     * @example
+     * ```typescript
+     * const updated = await customers.update('cust_abc123', {
+     *   email: 'new@acme.com'
+     * })
+     * ```
+     */
+    update(id: string, data: Partial<T>): Promise<T>;
+    /**
+     * Delete an entity by ID
+     *
+     * @param id - Entity ID
+     *
+     * @example
+     * ```typescript
+     * await customers.delete('cust_abc123')
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Count entities matching a filter
+     *
+     * @param filter - Optional filter expression
+     * @returns Count of matching entities
+     *
+     * @example
+     * ```typescript
+     * const total = await customers.count()
+     * const active = await customers.count({
+     *   field: 'status', op: 'eq', value: 'active'
+     * })
+     * ```
+     */
+    count(filter?: FilterExpression): Promise<number>;
+    /**
+     * Find entities matching a filter
+     *
+     * @param filter - Filter expression
+     * @returns Array of matching entities
+     *
+     * @example
+     * ```typescript
+     * const highValue = await customers.find({
+     *   and: [
+     *     { field: 'totalSpent', op: 'gte', value: 10000 },
+     *     { field: 'status', op: 'eq', value: 'active' }
+     *   ]
+     * })
+     * ```
+     */
+    find(filter: FilterExpression): Promise<T[]>;
+    /**
+     * Check if an entity matches a filter expression
+     *
+     * @param entity - The entity to check
+     * @param filter - The filter expression
+     * @returns True if the entity matches the filter
+     *
+     * @internal
+     */
+    protected matchesFilter(entity: T, filter: FilterExpression): boolean;
+    /**
+     * Build SQL WHERE clause from filter expression
+     *
+     * @param filter - Filter expression
+     * @returns Object with SQL clause and parameter values
+     *
+     * @internal
+     */
+    protected buildWhereClause(filter: FilterExpression): {
+        sql: string;
+        params: unknown[];
+    };
+    /**
+     * Convert filter operator to SQL operator
+     *
+     * @param op - Filter operator
+     * @returns SQL operator string
+     *
+     * @internal
+     */
+    protected operatorToSql(op: FilterOp): string;
+}
+/**
+ * Collection error types
+ */
+export declare class CollectionError extends Error {
+    readonly code: 'NOT_FOUND' | 'VALIDATION' | 'STORAGE' | 'CONFLICT';
+    readonly entityId?: string | undefined;
+    constructor(message: string, code: 'NOT_FOUND' | 'VALIDATION' | 'STORAGE' | 'CONFLICT', entityId?: string | undefined);
+}
+/**
+ * Entity not found error
+ */
+export declare class NotFoundError extends CollectionError {
+    constructor(collection: string, id: string);
+}
+/**
+ * Validation error
+ */
+export declare class ValidationError extends CollectionError {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+export default BaseCollection;
+//# sourceMappingURL=base.d.ts.map

package/dist/db/collections/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../db/collections/base.ts"],"names":[],"mappings":"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"}