@db3.ai/app 0.1.0-beta.1

package/dist/db/ActiveQueryBuilder.d.ts

@@ -0,0 +1,268 @@
+import type { Knex } from 'knex';
+import type { ActiveRecord, ActiveRecordClass } from './ActiveRecord.js';
+export interface VectorSimilarityOptions {
+    /** SQL result alias used for the computed vector distance. Defaults to `distance`. */
+    as?: string;
+    /** Optional maximum vector distance for filtering candidate rows. */
+    maxDistance?: number;
+    /** Whether to order rows by closest distance. Defaults to ascending distance. */
+    orderBy?: 'asc' | 'desc' | false;
+}
+/**
+ * Field-aware query builder that wraps Knex.
+ *
+ * Add wrapper methods as you need them. `toKnex()` is the escape hatch for raw
+ * Knex operations.
+ */
+export declare class ActiveQueryBuilder<TRecord extends ActiveRecord> {
+    private readonly Model;
+    private readonly db;
+    private readonly qb;
+    private readonly includedFields;
+    private readonly includedRelations;
+    private selectedFields;
+    private softDeleteScope;
+    constructor(Model: ActiveRecordClass<TRecord>, db: Knex);
+    /**
+     * Includes soft-deleted rows in query results and write operations.
+     */
+    withTrashed(): this;
+    /**
+     * Restricts the query to soft-deleted rows only.
+     */
+    onlyTrashed(): this;
+    /**
+     * Restricts the query to rows that have not been soft deleted.
+     */
+    withoutTrashed(): this;
+    /**
+     * Includes an opt-in field that normal fetches omit by default.
+     */
+    withField(fieldName: string): this;
+    /**
+     * Eager-loads a link field and serializes it as nested model JSON.
+     *
+     * The relation name may be the logical link field name, the target model table
+     * name, or the target model class name. Prefer the field name when a model has
+     * more than one link to the same table.
+     */
+    with(relationName: string): this;
+    /**
+     * Restricts hydrated query results to the requested logical model fields.
+     *
+     * This is intended for bounded read models and polling endpoints that should
+     * not load large model columns they do not render.
+     *
+     * @param fieldNames - Logical model field names to select.
+     * @returns This query builder.
+     *
+     * @example
+     * const pages = await WebsitePage
+     * 	.where('website', websiteId)
+     * 	.select('analyzeStatus', 'analyzeData')
+     * 	.all();
+     */
+    select(...fieldNames: string[]): this;
+    /**
+     * Adds field-aware equality conditions from an object.
+     */
+    where(criteria: Record<string, unknown>): this;
+    /**
+     * Adds a field-aware `where field = value` condition.
+     */
+    where(fieldName: string, value: unknown): this;
+    /**
+     * Adds a field-aware `where field operator value` condition.
+     */
+    where(fieldName: string, operator: string, value: unknown): this;
+    /**
+     * Adds a primary-key equality condition.
+     */
+    wherePk(id: unknown): this;
+    /**
+     * Adds a field-aware `where in (...)` condition.
+     */
+    whereIn(fieldName: string, values: unknown[]): this;
+    /**
+     * Adds a field-aware `where column is null` condition.
+     */
+    whereNull(fieldName: string): this;
+    /**
+     * Adds a field-aware `where column is not null` condition.
+     */
+    whereNotNull(fieldName: string): this;
+    /**
+     * Adds a raw where clause.
+     *
+     * Prefer field-aware methods where possible. Use parameter bindings to avoid
+     * SQL injection when using raw SQL.
+     */
+    whereRaw(sql: string, bindings?: readonly unknown[]): this;
+    /**
+     * Adds a dialect-aware vector similarity projection, optional distance filter,
+     * and closest-first ordering for a vector field.
+     *
+     * @param fieldName - Logical vector field name.
+     * @param vector - Query vector to compare against the stored field.
+     * @param options - Projection alias, optional distance threshold, and ordering.
+     * @returns This query builder.
+     *
+     * @example
+     * WebsiteEmbedding
+     * 	.query()
+     * 	.where('website', websiteId)
+     * 	.whereVectorSimilarTo('embedding', queryVector)
+     * 	.limit(10)
+     * 	.toKnex()
+     */
+    whereVectorSimilarTo(fieldName: string, vector: readonly number[], options?: VectorSimilarityOptions): this;
+    /**
+     * Returns whether the active database dialect can run vector similarity search.
+     *
+     * @returns True when `whereVectorSimilarTo()` can build SQL for this connection.
+     */
+    supportsVectorSimilaritySearch(): boolean;
+    /**
+     * Returns a model-visible message for unsupported vector similarity dialects.
+     *
+     * @returns Readable unsupported-dialect message.
+     */
+    vectorSimilarityUnsupportedMessage(): string;
+    /**
+     * Adds field-aware ordering.
+     */
+    orderBy(fieldName: string, direction?: 'asc' | 'desc'): this;
+    /**
+     * Limits the number of returned records.
+     */
+    limit(count: number): this;
+    /**
+     * Offsets returned records.
+     */
+    offset(count: number): this;
+    /**
+     * Escape hatch for raw database column names.
+     *
+     * This bypasses field conversion and validation. Use it for low-level cases,
+     * not normal application queries.
+     */
+    whereColumn(column: string, value: unknown): this;
+    whereColumn(column: string, operator: string, value: unknown): this;
+    /**
+     * Executes the query and returns the first hydrated record, or null.
+     */
+    first(): Promise<TRecord | null>;
+    /**
+     * Executes the query and returns the first hydrated record.
+     *
+     * @returns First matching record.
+     * @throws {RecordNotFoundError} When the query has no matching rows.
+     *
+     * @example
+     * const user = await User
+     * 	.where('email', email)
+     * 	.firstOrFail();
+     */
+    firstOrFail(): Promise<TRecord>;
+    /**
+     * Executes the query and returns hydrated records.
+     */
+    all(): Promise<TRecord[]>;
+    /**
+     * Counts matching records without hydrating or transferring model rows.
+     *
+     * @param fieldName - Optional logical field whose non-null values should be counted.
+     * @returns Number of matching records or non-null field values.
+     *
+     * @example
+     * const keywordCount = await Keywords
+     * 	.where('website', websiteId)
+     * 	.count();
+     */
+    count(fieldName?: string): Promise<number>;
+    /**
+     * Updates matching rows using field-aware assignment/conversion.
+     *
+     * This does not load records before updating them.
+     */
+    patch(input: Record<string, unknown>): Promise<number>;
+    /**
+     * Deletes matching rows, using soft deletes when the model opts in.
+     */
+    delete(): Promise<number>;
+    /**
+     * Physically deletes matching rows, bypassing soft delete behavior.
+     */
+    forceDelete(): Promise<number>;
+    /**
+     * Restores matching soft-deleted rows by clearing their delete timestamp.
+     */
+    restore(): Promise<number>;
+    /**
+     * Returns a scoped clone of the underlying Knex query builder.
+     *
+     * After calling this, you are outside the ActiveRecord hydration layer. Raw
+     * Knex results will not automatically become model instances.
+     */
+    toKnex(): Knex.QueryBuilder;
+    /**
+     * Looks up a field by logical model field name.
+     */
+    private getField;
+    /**
+     * Looks up a field and requires it to be a native vector field.
+     *
+     * @param fieldName - Logical model field name.
+     * @returns Native vector field instance.
+     */
+    private getVectorField;
+    /**
+     * Builds a dialect-aware vector distance expression for a vector field.
+     *
+     * @param field - Vector field being compared.
+     * @param vector - Query vector to compare against.
+     * @returns SQL expression and bindings for the active dialect.
+     */
+    private vectorDistanceSql;
+    /**
+     * Returns the supported vector-search dialect name for this query connection.
+     *
+     * @returns Supported dialect name, or null when not supported.
+     */
+    private vectorDistanceDialect;
+    /**
+     * Returns a model-table-qualified database column name for field-aware clauses.
+     *
+     * @param field - Model field or metadata whose storage column should be referenced.
+     * @returns Column qualified with the ActiveRecord model table.
+     */
+    private qualifiedColumn;
+    /**
+     * Looks up a requested relation and requires it to resolve to one link field.
+     */
+    private getRelationField;
+    /**
+     * Loads included link records in batches and attaches them to each record.
+     */
+    private loadIncludedRelations;
+    /**
+     * Loads one included link relation for all hydrated records.
+     */
+    private loadIncludedRelation;
+    /**
+     * Attaches loaded relation records to the bound link fields.
+     */
+    private attachLoadedRelation;
+    /**
+     * Returns table-qualified columns for fields included in model hydration.
+     */
+    private selectedColumns;
+    /**
+     * Returns true when a field should be included in hydrated query results.
+     */
+    private shouldSelectField;
+    /**
+     * Applies the current soft-delete scope to a Knex query clone.
+     */
+    private applySoftDeleteScope;
+}