@happyvertical/smrt-core 0.30.0

package/dist/collection.d.ts

@@ -0,0 +1,894 @@
+import { SmrtClassOptions, SmrtClass } from './class';
+import { CollectionCacheConfig } from './collection-cache';
+import { SmrtObject } from './object';
+/**
+ * Keys from SmrtObject and SmrtClass that should not appear as user-facing
+ * create/update input fields. These are framework-internal properties.
+ */
+type SmrtInternalKeys = keyof SmrtClass | '_tableName' | '_loadedRelationships' | '_id' | '_slug' | '_context' | '_ai' | '_fs' | '_db' | '_className' | 'options' | '_skipLoad' | '_skipAutoEmbeddings' | '_extractingFields' | 'initialize' | 'save' | 'delete' | 'loadFromId' | 'loadFromSlug' | 'is' | 'do' | 'toJSON' | 'transformJSON';
+/**
+ * Input type for `collection.create()`. Constrains input to valid model fields
+ * while preserving backwards compatibility via an index signature escape hatch.
+ *
+ * Provides IDE autocompletion for known fields from the model class while still
+ * accepting arbitrary keys for dynamic usage patterns (e.g., STI meta fields).
+ *
+ * @example
+ * ```typescript
+ * // IDE will suggest: name, price, quantity, categoryId, etc.
+ * await productCollection.create({
+ *   name: 'Widget',
+ *   price: 9.99,
+ *   _meta_type: 'SpecialProduct', // STI discriminator
+ * });
+ * ```
+ */
+export type SmrtCreateInput<T extends SmrtObject> = Partial<Omit<{
+    [K in keyof T as T[K] extends (...args: any[]) => any ? never : K]: T[K];
+}, SmrtInternalKeys>> & {
+    /** STI discriminator for polymorphic creation */
+    _meta_type?: string;
+    /** Skip database loading (framework internal) */
+    _skipLoad?: boolean;
+    /** Skip save-time embedding auto-generation (framework internal) */
+    _skipAutoEmbeddings?: boolean;
+    /** Allow arbitrary additional fields for dynamic usage */
+    [key: string]: unknown;
+};
+/**
+ * WHERE clause type for `collection.list()`.
+ *
+ * Uses `Record<string, unknown>` because WHERE keys often include operator
+ * suffixes (e.g., `'price >'`, `'name like'`, `'status in'`) which can't be
+ * expressed as mapped types from model properties. Runtime validation in
+ * `convertWhereKeys()` handles field and operator checking.
+ */
+export type SmrtWhereClause<T extends SmrtObject> = Record<string, unknown>;
+/**
+ * Configuration options for SmrtCollection
+ */
+export interface SmrtCollectionOptions extends SmrtClassOptions {
+}
+/**
+ * Typed CRUD collection for a specific `SmrtObject` subclass.
+ *
+ * Each concrete collection pairs with exactly one model class via the required
+ * `static readonly _itemClass` property. Use the static `create()` factory —
+ * not `new` — to get a fully initialized, ready-to-query instance.
+ *
+ * Key capabilities:
+ * - **Query**: `list()`, `get()`, `count()`, `query()` (raw SQL), `listByIds()`
+ * - **Mutation**: `create()`, `getOrUpsert()`, `delete()`
+ * - **Eager loading**: pass `include: ['fieldName']` to `list()` to avoid N+1 queries
+ * - **STI support**: automatically filters by `_meta_type` for child collections;
+ *   polymorphically hydrates the correct subclass when listing/getting
+ * - **Interceptors**: all read/write paths run `GlobalInterceptors` hooks
+ *   (used by multi-tenancy, audit logging, etc.)
+ *
+ * @typeParam ModelType - The `SmrtObject` subclass managed by this collection
+ *
+ * @example
+ * ```typescript
+ * @smrt()
+ * class Product extends SmrtObject {
+ *   name: string = '';
+ *   price: number = 0.0;
+ * }
+ *
+ * @smrt()
+ * class Products extends SmrtCollection<Product> {
+ *   static readonly _itemClass = Product;
+ * }
+ *
+ * const products = await Products.create({ db: myDb });
+ * const widget = await products.create({ name: 'Widget', price: 9.99 });
+ * const all = await products.list({ where: { 'price >': 5 }, orderBy: 'price ASC' });
+ * ```
+ */
+export declare class SmrtCollection<ModelType extends SmrtObject> extends SmrtClass {
+    /**
+     * Cached fields for sync access during queries.
+     * Populated during create() to avoid async getFields() calls on every query.
+     * @private
+     */
+    private _cachedFields;
+    private getRegisteredItemClass;
+    private getResolvedItemClassName;
+    private getResolvedItemQualifiedName;
+    /**
+     * Convert WHERE clause field names from camelCase to snake_case while preserving operators.
+     * Validates operators and field names to prevent SQL injection and invalid queries.
+     *
+     * Uses cached fields for sync access (issue #663) to avoid async overhead on every query.
+     *
+     * @param where - WHERE clause object with camelCase field names
+     * @returns WHERE clause object with snake_case field names
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Input: { 'typeId': 'foo', 'categoryId >': 100 }
+     * // Output: { 'type_id': 'foo', 'category_id >': 100 }
+     * ```
+     */
+    private convertWhereKeys;
+    /**
+     * Gets the class constructor for items in this collection
+     */
+    protected get _itemClass(): (new (options: any) => ModelType) & {
+        create(options: any): ModelType | Promise<ModelType>;
+    };
+    /**
+     * Static reference to the item class constructor
+     */
+    static readonly _itemClass: any;
+    /**
+     * Validates that the collection is properly configured
+     * Call this during development to catch configuration issues early
+     */
+    static validate(): void;
+    /**
+     * Database table name for this collection
+     */
+    _tableName: string;
+    /**
+     * Creates a new SmrtCollection instance
+     *
+     * @deprecated Use the static create() factory method instead
+     * @param options - Configuration options
+     */
+    constructor(options?: SmrtCollectionOptions);
+    /**
+     * Factory method — the recommended way to instantiate a collection.
+     *
+     * Creates the collection instance, calls `initialize()`, and pre-populates
+     * the field cache used by synchronous query helpers.
+     *
+     * Pass the same `options` object you received in a `SmrtObject` constructor
+     * or a `SvelteKit` load function to share the database connection.
+     *
+     * @param options - Database, AI, filesystem, and other configuration options.
+     *   At minimum, provide `db` (or `persistence`) to connect to a database.
+     * @returns A fully initialized, ready-to-query collection instance
+     *
+     * @example
+     * ```typescript
+     * // Share a DB connection from a SvelteKit load function
+     * const products = await Products.create(event.locals.smrtOptions);
+     *
+     * // Explicit configuration
+     * const products = await Products.create({
+     *   db: myDb,
+     *   ai: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY },
+     * });
+     * ```
+     */
+    static create<T extends SmrtCollection<any>>(this: new (options?: SmrtCollectionOptions) => T, options?: SmrtClassOptions): Promise<T>;
+    /**
+     * Async initialization hook for the collection.
+     *
+     * Called automatically by the static `create()` factory. In most cases you
+     * do not need to call this directly — use `create()` instead.
+     *
+     * Runtime schema checks are deferred until a query actually touches the
+     * backing table. This keeps collection construction safe during SSR and
+     * import-time module evaluation without mutating application schema.
+     *
+     * @returns This instance (enables chaining)
+     */
+    initialize(): Promise<this>;
+    /**
+     * Verify that the collection's backing table exists before running a query.
+     *
+     * This is a fail-fast check only. It does not create or alter schema.
+     */
+    ensureStorageReady(): Promise<void>;
+    /**
+     * Find a single record by criteria (convenience method - delegates to get())
+     *
+     * @param options - Query options with where clause
+     * @returns Promise resolving to the object or null if not found
+     *
+     * @example
+     * ```typescript
+     * const councils = await Councils.create({ persistence: { type: 'sql', url: 'db.sqlite' } });
+     * const council = await councils.findOne({ where: { name: 'Example Council' } });
+     * ```
+     */
+    findOne(options: {
+        where: Record<string, any>;
+    }): Promise<ModelType | null>;
+    /**
+     * Find a record by ID (convenience method - delegates to get())
+     *
+     * @param id - Record ID to find (string or Field instance)
+     * @returns Promise resolving to the object or null if not found
+     *
+     * @example
+     * ```typescript
+     * const councils = await Councils.create({ persistence: { type: 'sql', url: 'db.sqlite' } });
+     * const council = await councils.findById('uuid-123');
+     *
+     * // Also works with Field instances (e.g., from foreignKey fields)
+     * const meeting = new Meeting({ councilId: 'uuid-123' });
+     * const council = await councils.findById(meeting.councilId);
+     * ```
+     */
+    findById(id: string): Promise<ModelType | null>;
+    /**
+     * Find all records matching criteria (convenience method - delegates to list())
+     *
+     * @param options - Query options (where, orderBy, limit, etc.)
+     * @returns Promise resolving to array of objects
+     *
+     * @example
+     * ```typescript
+     * const councils = await Councils.create({ persistence: { type: 'sql', url: 'db.sqlite' } });
+     * const active = await councils.findAll({ where: { status: 'active' } });
+     * ```
+     */
+    findAll(options?: {
+        where?: SmrtWhereClause<ModelType>;
+        orderBy?: string | string[];
+        limit?: number;
+        offset?: number;
+        include?: string[];
+    }): Promise<ModelType[]>;
+    /**
+     * Find multiple objects by their IDs in a single query.
+     *
+     * This is a convenience method that avoids N+1 queries when you have
+     * a list of IDs and need to fetch the corresponding records.
+     *
+     * @param ids - Array of UUIDs to fetch
+     * @returns Promise resolving to array of objects (order not guaranteed)
+     *
+     * @example
+     * ```typescript
+     * const profiles = await profileCollection.listByIds(['id1', 'id2', 'id3']);
+     * ```
+     */
+    listByIds(ids: string[]): Promise<ModelType[]>;
+    /**
+     * Resolve the effective cache config for a read (issue #1498).
+     *
+     * Per-call options win: `false` forces a fresh read, `{ ttl }` enables
+     * caching for this call. Otherwise falls back to the model-level
+     * `@smrt({ cache })` config (inheritance-aware). Returns undefined when
+     * the read should go straight to the database — the default.
+     */
+    private resolveReadCacheConfig;
+    /**
+     * Execute a SELECT, optionally through the collection read cache.
+     *
+     * The cache key is the final SQL + bound parameters — computed after
+     * interceptors (tenancy filters) and STI discriminators are applied, so
+     * differently-scoped queries can never share an entry. Cached values are
+     * raw rows; hydration and read interceptors still run on every call.
+     */
+    private queryRowsWithCache;
+    /**
+     * Retrieves a single object from the collection by ID, slug, or a custom filter.
+     *
+     * Filter resolution:
+     * - UUID string → `WHERE id = ?`
+     * - Non-UUID string → `WHERE slug = ? AND context = ''`
+     * - Object → `WHERE <key> = <value> [AND ...]`
+     *
+     * For STI child collections, an `AND _meta_type = '<qualifiedName>'` clause is
+     * automatically appended so you only receive the correct subclass.
+     *
+     * Runs `beforeGet` / `afterGet` interceptors (used by multi-tenancy, etc.).
+     *
+     * @param filter - UUID string, slug string, or a WHERE conditions object
+     * @param options.cache - Opt-in read-through cache for this call
+     *   (`{ ttl }` in milliseconds), or `false` to force a fresh read when the
+     *   model opted in via `@smrt({ cache })`. Defaults to the model config.
+     * @returns The matching object instance, or `null` if not found
+     *
+     * @example
+     * ```typescript
+     * // By UUID
+     * const product = await products.get('550e8400-e29b-41d4-a716-446655440000');
+     *
+     * // By slug
+     * const product = await products.get('my-widget');
+     *
+     * // By custom filter
+     * const product = await products.get({ sku: 'WID-001' });
+     *
+     * // Cached read (memoized for 60s, invalidated on writes)
+     * const product = await products.get('my-widget', { cache: { ttl: 60_000 } });
+     * ```
+     *
+     * @see {@link list} for multiple results
+     * @see {@link findById} / {@link findOne} for convenience aliases
+     */
+    get(filter: string | Record<string, any>, options?: {
+        cache?: CollectionCacheConfig | false;
+    }): Promise<ModelType | null>;
+    /**
+     * Lists records from the collection with flexible filtering options
+     *
+     * @param options - Query options object
+     * @param options.where - Record of conditions to filter results. Each key can include an operator
+     *                      separated by a space (e.g., 'price >', 'name like'). Default operator is '='.
+     * @param options.offset - Number of records to skip
+     * @param options.limit - Maximum number of records to return
+     * @param options.orderBy - Field(s) to order results by, with optional direction
+     *
+     * @example
+     * ```typescript
+     * // Find active products priced between $100-$200
+     * await collection.list({
+     *   where: {
+     *     'price >': 100,
+     *     'price <=': 200,
+     *     'status': 'active',              // equals operator is default
+     *     'category in': ['A', 'B', 'C'],  // IN operator for arrays
+     *     'name like': '%shirt%',          // LIKE for pattern matching
+     *     'deleted_at !=': null            // exclude deleted items
+     *   },
+     *   limit: 10,
+     *   offset: 0
+     * });
+     *
+     * // Find users matching pattern but not in specific roles
+     * await users.list({
+     *   where: {
+     *     'email like': '%@company.com',
+     *     'active': true,
+     *     'role in': ['guest', 'blocked'],
+     *     'last_login <': lastMonth
+     *   }
+     * });
+     * ```
+     *
+     * @returns Promise resolving to an array of model instances
+     */
+    list(options?: {
+        where?: SmrtWhereClause<ModelType>;
+        offset?: number;
+        limit?: number;
+        orderBy?: string | string[];
+        /**
+         * Relationships to eagerly load (avoids N+1 query problem)
+         * @example
+         * ```typescript
+         * // Load orders with their customers pre-loaded
+         * const orders = await orderCollection.list({
+         *   include: ['customerId']
+         * });
+         * // Access customer without additional query
+         * orders[0].getRelated('customerId');
+         * ```
+         */
+        include?: string[];
+        /**
+         * Opt-in read-through cache for this call (issue #1498).
+         *
+         * Pass `{ ttl }` (milliseconds) to memoize the result rows keyed by
+         * the final query shape. Mutations through SMRT invalidate the
+         * table's entries automatically. Pass `false` to force a fresh read
+         * when the model opted in via `@smrt({ cache })`. Defaults to the
+         * model-level config; uncached when neither is set.
+         *
+         * @example
+         * ```typescript
+         * const published = await resumes.list({
+         *   where: { status: 'published' },
+         *   cache: { ttl: 60_000 },
+         * });
+         * ```
+         */
+        cache?: CollectionCacheConfig | false;
+    }): Promise<ModelType[]>;
+    /**
+     * Eagerly load relationships for a collection of instances
+     *
+     * Optimizes loading by batching queries for foreignKey relationships to avoid N+1 queries.
+     *
+     * @param instances - Array of object instances to load relationships for
+     * @param relationships - Array of relationship field names to load
+     * @private
+     */
+    private eagerLoadRelationships;
+    /**
+     * Batch load foreignKey relationships to avoid N+1 queries
+     *
+     * @param instances - Instances to load relationships for
+     * @param fieldName - Name of the foreignKey field
+     * @param relationship - Relationship metadata
+     * @private
+     */
+    private batchLoadForeignKeys;
+    /**
+     * Batch load oneToMany relationships
+     *
+     * @param instances - Instances to load relationships for
+     * @param fieldName - Name of the oneToMany field
+     * @param relationship - Relationship metadata
+     * @private
+     */
+    private batchLoadOneToMany;
+    /**
+     * Batch-load manyToMany relationships through a junction table.
+     *
+     * Issues two queries instead of N: one against the junction table to map
+     * source IDs to target IDs, and one against the target table to hydrate
+     * the related rows. Results are grouped by source instance.
+     *
+     * @param instances - Instances whose manyToMany field should be populated
+     * @param fieldName - Name of the @manyToMany decorated field
+     * @param relationship - Relationship metadata from the registry
+     * @private
+     */
+    private batchLoadManyToMany;
+    /**
+     * Creates and persists a new instance of the collection's item class.
+     *
+     * Instantiates the model with the given field values, calls `initialize()`,
+     * assigns a UUID if none is provided, then calls `save()` to write the row
+     * to the database.
+     *
+     * For STI collections, pass `_meta_type` to create a specific subclass.
+     * The correct constructor is resolved via `ObjectRegistry` (polymorphic creation).
+     *
+     * @param options - Field values for the new object. Accepts any public field on
+     *   the model class plus the STI `_meta_type` discriminator.
+     * @returns The newly created and saved model instance
+     * @throws {ValidationError} If a `required` field is missing or a unique constraint is violated
+     * @throws {DatabaseError} If the write fails
+     *
+     * @example
+     * ```typescript
+     * // Regular creation
+     * const product = await products.create({ name: 'Widget', price: 9.99 });
+     * console.log(product.id); // UUID assigned during save
+     *
+     * // STI polymorphic creation
+     * const article = await contents.create({
+     *   _meta_type: '@happyvertical/smrt-content:Article',
+     *   title: 'Hello World',
+     * });
+     * ```
+     *
+     * @see {@link getOrUpsert} to avoid duplicates by finding-or-creating
+     */
+    create(options: SmrtCreateInput<ModelType>): Promise<ModelType>;
+    /**
+     * Creates an instance of the correct subclass for STI polymorphic queries
+     *
+     * @param className - Name of the class to instantiate (from _meta_type)
+     * @param options - Data to initialize the instance with
+     * @returns Promise resolving to the instance of the correct subclass
+     * @private
+     */
+    private createPolymorphic;
+    /**
+     * Finds an existing record matching `data` or creates it if not found.
+     *
+     * Look-up priority:
+     * 1. `data.id` — query by primary key
+     * 2. `data.slug` — query by slug + context
+     * 3. Fallback — query by the full `data` object as a WHERE clause
+     *
+     * If a matching record is found, it is updated with any changed fields from
+     * `data` (diffed against the existing record) and saved. If no match is
+     * found, `defaults` are merged with `data` and a new record is created.
+     *
+     * @param data - The field values to find or upsert
+     * @param defaults - Extra default values applied only when creating a new record
+     * @returns The existing (possibly updated) or newly created object instance
+     *
+     * @example
+     * ```typescript
+     * // Find-or-create a tag by slug
+     * const tag = await tags.getOrUpsert({ slug: 'javascript', name: 'JavaScript' });
+     *
+     * // With defaults applied only on creation
+     * const user = await users.getOrUpsert(
+     *   { email: 'alice@example.com' },
+     *   { role: 'member', active: true },
+     * );
+     * ```
+     *
+     * @see {@link create} for always-insert semantics
+     * @see {@link get} for read-only lookup
+     */
+    getOrUpsert(data: any, defaults?: any): Promise<ModelType>;
+    /**
+     * Gets differences between an existing object and new data
+     *
+     * @param existing - Existing object
+     * @param data - New data
+     * @returns Object containing only the changed fields
+     */
+    getDiff(existing: Record<string, any>, data: Record<string, any>): Promise<Record<string, any> | null>;
+    private getDiffSync;
+    /**
+     * Gets field definitions for the collection's item class
+     *
+     * @returns Object containing field definitions
+     */
+    getFields(): Promise<Record<string, any>>;
+    /**
+     * Normalize user input into the model's logical field names before diffing or creation.
+     *
+     * Accepts both camelCase and snake_case keys while preserving framework meta fields.
+     */
+    private normalizeLogicalData;
+    /**
+     * Preserve persisted core timestamp fields during lightweight hydration.
+     */
+    private withHydratedCoreFields;
+    /**
+     * Treat date-equivalent values as unchanged even if their runtime types differ.
+     */
+    private areEquivalentValues;
+    /**
+     * Convert supported date inputs into comparable timestamps.
+     */
+    private toComparableTime;
+    /**
+     * Gets field definitions synchronously from cache.
+     *
+     * This method provides sync access to fields for use in query methods,
+     * avoiding the async overhead of getFields() on every query.
+     * Fields are cached during create() initialization.
+     *
+     * @returns Map containing field definitions
+     * @private
+     */
+    getFieldsSync(): Record<string, any>;
+    /**
+     * Generates database schema for the collection's item class
+     *
+     * Leverages ObjectRegistry's cached schema for instant retrieval.
+     *
+     * @returns Schema object for database setup
+     */
+    generateSchema(): Promise<string>;
+    /**
+     * Gets the database table name for this collection
+     */
+    get tableName(): string;
+    /**
+     * Generates a table name from the collection class name
+     *
+     * @returns Generated table name
+     */
+    generateTableName(): string;
+    /**
+     * Deletes a record from the collection by ID
+     *
+     * Loads the object and calls its delete() method, ensuring all interceptors
+     * and lifecycle hooks (beforeDelete/afterDelete) are executed correctly.
+     *
+     * @param id - The ID of the record to delete
+     * @returns Promise resolving to true if deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const success = await collection.delete('some-uuid');
+     * if (success) {
+     *   console.log('Record deleted');
+     * }
+     * ```
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Returns the number of records matching the given filter conditions.
+     *
+     * Executes a `SELECT COUNT(*)` query with the same WHERE conversion as
+     * `list()` (camelCase field names, operator suffixes, STI auto-filtering).
+     * `limit`, `offset`, and `orderBy` are not applicable and are ignored.
+     *
+     * Note: `count()` is never served from the read cache (issue #1498) — only
+     * `list()`/`get()` are. On a page that caches `list()`, a `count()` issued
+     * in the same request reflects the live database and may briefly diverge
+     * from the cached rows within the TTL window.
+     *
+     * @param options.where - Filter conditions (same syntax as `list()`)
+     * @returns Total count of matching records as an integer
+     *
+     * @example
+     * ```typescript
+     * const total = await products.count();
+     * const activeCount = await products.count({ where: { status: 'active' } });
+     * const expensiveCount = await products.count({ where: { 'price >': 100 } });
+     * ```
+     *
+     * @see {@link list} for retrieving the actual records
+     */
+    count(options?: {
+        where?: Record<string, any>;
+    }): Promise<number>;
+    /**
+     * Execute a raw SQL query and hydrate results as collection item instances
+     *
+     * Provides full SQL power for complex queries (JOINs, CTEs, NOT EXISTS, etc.)
+     * while still returning properly hydrated SMRT objects.
+     *
+     * @param sql - Raw SQL query string (should select from this.tableName)
+     * @param params - Query parameters for prepared statement
+     * @returns Promise resolving to array of hydrated model instances
+     *
+     * @example
+     * ```typescript
+     * // Find meetings without corresponding recaps (NOT EXISTS pattern)
+     * const meetings = await meetingCollection.query(`
+     *   SELECT m.* FROM meetings m
+     *   WHERE m.start_date < datetime('now')
+     *   AND NOT EXISTS (
+     *     SELECT 1 FROM contents c
+     *     WHERE c.meeting_id = m.id
+     *     AND c._meta_type = 'MeetingRecap'
+     *   )
+     *   ORDER BY m.start_date DESC
+     *   LIMIT ?
+     * `, [10]);
+     *
+     * // Complex JOIN query
+     * const products = await productCollection.query(`
+     *   SELECT p.* FROM products p
+     *   INNER JOIN categories c ON p.category_id = c.id
+     *   WHERE c.name = ? AND p.price > ?
+     *   ORDER BY p.price ASC
+     * `, ['Electronics', 100]);
+     * ```
+     */
+    query(sql: string, params?: any[], options?: {
+        allowRawOnTenantScoped?: boolean;
+    }): Promise<ModelType[]>;
+    private hydrateResultRow;
+    /**
+     * Remember collection-level context
+     *
+     * Stores context applicable to all instances of this collection type.
+     * Use for patterns that apply to the entire collection (e.g., default parsing strategies).
+     *
+     * @param options - Context options
+     * @returns Promise that resolves when context is stored
+     * @example
+     * ```typescript
+     * // Remember a default parsing strategy for all documents
+     * await documentCollection.remember({
+     *   scope: 'parser/default',
+     *   key: 'selector',
+     *   value: { pattern: '.content article' },
+     *   confidence: 0.8
+     * });
+     *
+     * // Update an existing context entry by specifying id
+     * await documentCollection.remember({
+     *   id: 'existing-context-id',
+     *   scope: 'parser/default',
+     *   key: 'selector',
+     *   value: { pattern: '.content main article' },
+     *   confidence: 0.85
+     * });
+     * ```
+     */
+    remember(options: {
+        id?: string;
+        scope: string;
+        key: string;
+        value: any;
+        metadata?: any;
+        confidence?: number;
+        version?: number;
+        expiresAt?: Date;
+    }): Promise<void>;
+    /**
+     * Recall collection-level context
+     *
+     * Retrieves context that applies to all instances of this collection.
+     *
+     * @param options - Recall options
+     * @returns Promise resolving to the context value or null if not found
+     * @example
+     * ```typescript
+     * // Recall default parsing strategy
+     * const strategy = await documentCollection.recall({
+     *   scope: 'parser/default',
+     *   key: 'selector',
+     *   minConfidence: 0.5
+     * });
+     * ```
+     */
+    recall(options: {
+        scope: string;
+        key: string;
+        includeAncestors?: boolean;
+        minConfidence?: number;
+    }): Promise<any | null>;
+    /**
+     * Recall all collection-level context in a scope
+     *
+     * Returns a Map of key -> value for all collection contexts matching the criteria.
+     *
+     * @param options - Recall options
+     * @returns Promise resolving to Map of key -> value pairs
+     * @example
+     * ```typescript
+     * // Get all default strategies
+     * const strategies = await documentCollection.recallAll({
+     *   scope: 'parser/default',
+     *   minConfidence: 0.5
+     * });
+     * ```
+     */
+    recallAll(options?: {
+        scope?: string;
+        includeDescendants?: boolean;
+        minConfidence?: number;
+    }): Promise<Map<string, any>>;
+    /**
+     * Forget collection-level context
+     *
+     * Deletes collection context by scope and key.
+     *
+     * @param options - Context identification
+     * @returns Promise that resolves when context is deleted
+     * @example
+     * ```typescript
+     * // Remove a default strategy
+     * await documentCollection.forget({
+     *   scope: 'parser/default',
+     *   key: 'selector'
+     * });
+     * ```
+     */
+    forget(options: {
+        scope: string;
+        key: string;
+    }): Promise<void>;
+    /**
+     * Forget all collection-level context in a scope
+     *
+     * Deletes all collection contexts matching the scope pattern.
+     *
+     * @param options - Scope options
+     * @returns Promise resolving to number of contexts deleted
+     * @example
+     * ```typescript
+     * // Clear all default strategies
+     * const count = await documentCollection.forgetScope({
+     *   scope: 'parser/default',
+     *   includeDescendants: true
+     * });
+     * ```
+     */
+    forgetScope(options: {
+        scope: string;
+        includeDescendants?: boolean;
+    }): Promise<number>;
+    /**
+     * Semantic search by text query
+     *
+     * Generates an embedding for the query text and finds similar objects
+     * based on cosine similarity of stored embeddings.
+     *
+     * @param query - Text to search for
+     * @param options - Search options
+     * @param options.field - Specific field to search (defaults to first embedding field)
+     * @param options.limit - Maximum results to return (default: 10)
+     * @param options.minSimilarity - Minimum similarity threshold 0-1 (default: 0)
+     * @param options.where - Additional WHERE filters to apply
+     * @returns Promise resolving to array of objects with _similarity score
+     *
+     * @example
+     * ```typescript
+     * const results = await articles.semanticSearch('machine learning trends', {
+     *   limit: 10,
+     *   minSimilarity: 0.7
+     * });
+     *
+     * for (const article of results) {
+     *   console.log(`${article.title} (similarity: ${article._similarity})`);
+     * }
+     * ```
+     */
+    semanticSearch(query: string, options?: {
+        field?: string;
+        limit?: number;
+        minSimilarity?: number;
+        where?: Record<string, any>;
+    }): Promise<Array<ModelType & {
+        _similarity: number;
+    }>>;
+    /**
+     * Find objects similar to a given object
+     *
+     * Uses stored embeddings to find objects most similar to the provided object.
+     *
+     * @param object - Object to find similar items for (or object ID)
+     * @param options - Search options
+     * @param options.field - Specific field to compare (defaults to first embedding field)
+     * @param options.limit - Maximum results to return (default: 5)
+     * @param options.excludeSelf - Whether to exclude the source object (default: true)
+     * @returns Promise resolving to array of similar objects with _similarity score
+     *
+     * @example
+     * ```typescript
+     * const article = await articles.get('some-article-id');
+     * const similar = await articles.findSimilar(article, {
+     *   limit: 5,
+     *   excludeSelf: true
+     * });
+     * ```
+     */
+    findSimilar(object: ModelType | string, options?: {
+        field?: string;
+        limit?: number;
+        excludeSelf?: boolean;
+    }): Promise<Array<ModelType & {
+        _similarity: number;
+    }>>;
+    /**
+     * Find objects similar to a raw embedding vector
+     *
+     * Low-level method for finding objects by embedding similarity.
+     *
+     * @param embedding - Embedding vector to compare against
+     * @param options - Search options
+     * @param options.field - Field name to search (defaults to first embedding field)
+     * @param options.limit - Maximum results to return (default: 10)
+     * @param options.minSimilarity - Minimum similarity threshold 0-1 (default: 0)
+     * @param options.where - Additional WHERE filters to apply
+     * @returns Promise resolving to array of objects with _similarity score
+     *
+     * @example
+     * ```typescript
+     * // Using a pre-computed embedding
+     * const results = await articles.findSimilarToEmbedding(myEmbedding, {
+     *   limit: 10,
+     *   minSimilarity: 0.5
+     * });
+     * ```
+     */
+    findSimilarToEmbedding(embedding: number[], options?: {
+        field?: string;
+        limit?: number;
+        minSimilarity?: number;
+        where?: Record<string, any>;
+    }): Promise<Array<ModelType & {
+        _similarity: number;
+    }>>;
+    /**
+     * Generate missing embeddings for all objects in the collection
+     *
+     * Batch generates embeddings for objects that don't have them yet
+     * or have stale embeddings.
+     *
+     * @param options - Generation options
+     * @param options.batchSize - Number of objects to process at once (default: 50)
+     * @param options.onProgress - Progress callback
+     * @returns Promise resolving to generation statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await articles.generateMissingEmbeddings({
+     *   batchSize: 100,
+     *   onProgress: ({ completed, total }) => {
+     *     console.log(`Progress: ${completed}/${total}`);
+     *   }
+     * });
+     *
+     * console.log(`Generated: ${stats.generated}, Skipped: ${stats.skipped}`);
+     * ```
+     */
+    generateMissingEmbeddings(options?: {
+        batchSize?: number;
+        onProgress?: (progress: {
+            completed: number;
+            total: number;
+        }) => void;
+    }): Promise<{
+        generated: number;
+        skipped: number;
+    }>;
+}
+export {};
+//# sourceMappingURL=collection.d.ts.map