@vibesdotdev/storage 0.0.1

package/dist/record/base.d.ts

@@ -0,0 +1,186 @@
+/**
+ * StorageRecord Base Implementation
+ *
+ * Provides CRUD operations on a single table with relations.
+ * This is what gets resolved when you query for a storage/record descriptor.
+ *
+ * @example
+ * ```typescript
+ * const todos = new StorageRecord(todoDescriptor, adapter);
+ * await todos.initialize();
+ *
+ * const todo = await todos.create({
+ *   sessionId: 'session-123',
+ *   title: 'Implement storage',
+ *   status: 'in_progress'
+ * });
+ * ```
+ */
+import type { z } from 'zod/v4';
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+import type { StorageRecordDescriptor, StorageRelation } from '../schemas/record';
+import type { StorageRecordInterface, WhereFilter, QueryOptions, QueryResult, CreateInput, CreateManyOptions, UpdateInput, UpdateOptions, UpdateResult, DeleteOptions, DeleteResult, TransactionFn, AggregationFunction, AggregationOptions, AggregationResult, StreamOptions } from '../interfaces/record';
+export declare function applyCreateTimestamps(record: Record<string, unknown>, timestamps: StorageRecordDescriptor['timestamps'], now: string): void;
+export declare function applyUpdateTimestamp(record: Record<string, unknown>, update: Record<string, unknown>, timestamps: StorageRecordDescriptor['timestamps'], now: string): void;
+/**
+ * StorageRecord Implementation
+ *
+ * Implements StorageRecordInterface for single-table CRUD operations.
+ * Works with SQLite via the localdb adapter.
+ *
+ * Uses runtime query API to resolve the appropriate adapter based on
+ * the descriptor's allowedAdapters and defaultAdapter settings.
+ */
+export declare class StorageRecord<T = unknown> implements StorageRecordInterface<T, Record<string, StorageRelation>> {
+    readonly tableName: string;
+    readonly primaryKey: string;
+    readonly schema: z.ZodType<T>;
+    readonly relations: Record<string, StorageRelation>;
+    private descriptor;
+    private context;
+    private adapterCache;
+    private db;
+    private initialized;
+    private asMutableRecord;
+    private readStringField;
+    private readPrimaryKey;
+    /**
+     * Emit a lifecycle event via the runtime HookBus.
+     * Fire-and-forget: never blocks CRUD, silently catches errors.
+     */
+    private emitLifecycle;
+    constructor(descriptor: StorageRecordDescriptor, context: KindContext | Record<string, unknown>);
+    /**
+     * Resolve the adapter for this record using runtime query API.
+     *
+     * Uses the record's allowed adapters list and current scope to
+     * select the best available adapter.
+     */
+    private getAdapter;
+    /**
+     * Get adapter configuration based on record scope.
+     */
+    private getAdapterConfig;
+    /**
+     * Get base path for storage based on scope.
+     *
+     * Scope mapping:
+     * - global:  ~/.vibes/          (user-level, shared across projects)
+     * - project: ./.vibes/          (project-level, within .vibes dir)
+     * - local:   ./.vibes/          (alias for project)
+     * - auto:    ./.vibes/          (defaults to project scope)
+     */
+    private getBasePath;
+    /**
+     * Initialize the storage record
+     * - Creates table if it doesn't exist
+     * - Runs migrations
+     * - Creates indexes
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure the table has a `data` TEXT column required by StorageRecord CRUD operations.
+     *
+     * Inline migrations may create normalized column schemas that don't include a `data`
+     * column. StorageRecord's create/get/list/update/delete all use json_extract(data, ...)
+     * and INSERT INTO ... (primaryKey, data). If the table is empty and lacks `data`,
+     * it is safe to drop and recreate with the minimal (primaryKey, data) schema.
+     */
+    private ensureDataColumn;
+    /**
+     * Get database connection from adapter.
+     * Uses the typed ensureReady() / getDatabaseConnection() interface.
+     */
+    private getDatabase;
+    /**
+     * Create table from schema definition
+     */
+    private createTableFromSchema;
+    /**
+     * Build column definitions from schema and descriptor
+     */
+    private buildColumnDefinitions;
+    /**
+     * Create indexes from descriptor
+     */
+    private createIndexes;
+    /**
+     * Execute one or more SQL statements, splitting on `;` and running each
+     * via the prepared-statement path so bun:sqlite does not misinterpret `$`
+     * tokens inside string literals (e.g. json_extract paths).
+     */
+    private execStatements;
+    /**
+     * Run migrations from descriptor
+     */
+    private runMigrations;
+    create(data: CreateInput<T>): Promise<T>;
+    createMany(data: CreateInput<T>[], options?: CreateManyOptions): Promise<T[]>;
+    get(id: string, options?: Pick<QueryOptions<T, string & keyof this['relations']>, 'include' | 'select'>): Promise<T | null>;
+    getOrThrow(id: string, options?: Pick<QueryOptions<T, string & keyof this['relations']>, 'include' | 'select'>): Promise<T>;
+    getMany(ids: string[], options?: Pick<QueryOptions<T, string & keyof this['relations']>, 'include' | 'select'>): Promise<T[]>;
+    list(options?: QueryOptions<T, string & keyof this['relations']>): Promise<QueryResult<T>>;
+    findFirst(options?: QueryOptions<T, string & keyof this['relations']>): Promise<T | null>;
+    findFirstOrThrow(options?: QueryOptions<T, string & keyof this['relations']>): Promise<T>;
+    exists(id: string): Promise<boolean>;
+    count(where?: WhereFilter<T>): Promise<number>;
+    update(id: string, data: UpdateInput<T>, _options?: UpdateOptions): Promise<T>;
+    updateMany(where: WhereFilter<T>, data: UpdateInput<T>, options?: UpdateOptions): Promise<UpdateResult>;
+    upsert(id: string, create: CreateInput<T>, update: UpdateInput<T>): Promise<T>;
+    delete(id: string, options?: DeleteOptions): Promise<DeleteResult>;
+    deleteMany(where: WhereFilter<T>, options?: DeleteOptions): Promise<DeleteResult>;
+    restore(id: string): Promise<T>;
+    aggregate(options: AggregationOptions<T> & {
+        function: AggregationFunction;
+    }): Promise<AggregationResult[]>;
+    transaction<U>(fn: TransactionFn<U>): Promise<U>;
+    stream(options?: StreamOptions<T>): AsyncIterable<T>;
+    batch(operations: Array<{
+        type: 'create' | 'update' | 'delete';
+        data?: unknown;
+        id?: string;
+    }>): Promise<unknown[]>;
+    validate(data: unknown): Promise<{
+        success: boolean;
+        data?: T;
+        errors?: z.ZodError;
+    }>;
+    getAdapterId(): string;
+    close(): Promise<void>;
+    private ensureInitialized;
+    private generateId;
+    private buildWhereClause;
+    private buildOrderBy;
+    private loadRelations;
+    private loadRelation;
+    /**
+     * Load many-to-many relation through junction table
+     */
+    private loadManyToManyRelation;
+    /**
+     * Find a junction table column that stores this record's primary key.
+     */
+    private findJunctionForeignKeyColumn;
+    /**
+     * Extract target IDs from junction rows.
+     */
+    private extractJunctionTargetIds;
+    /**
+     * True when a field name is likely an identifier / foreign key field.
+     */
+    private isLikelyIdColumn;
+    /**
+     * Escape SQL identifier safely for query fragments.
+     */
+    private quoteIdentifier;
+    search(query: string, options?: import('../interfaces/record').SearchOptions<T, string & keyof this['relations']>): Promise<import('../interfaces/record').SearchResult<T>>;
+    getDescendants(id: string, options?: import('../interfaces/record').HierarchyOptions<T, string & keyof this['relations']>): Promise<import('../interfaces/record').QueryResult<T & {
+        depth: number;
+        path?: string[];
+    }>>;
+    getAncestors(id: string, _options?: import('../interfaces/record').QueryOptions<T, string & keyof this['relations']>): Promise<T[]>;
+    getTree(options?: import('../interfaces/record').HierarchyOptions<T, string & keyof this['relations']>): Promise<import('../interfaces/record').TreeNode<T>[]>;
+    raw<R = unknown>(sql: string, ...params: unknown[]): Promise<R[]>;
+    queryRaw<R>(options: import('../interfaces/record').RawQueryOptions<R>): Promise<R[]>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/record/base.d.ts.map

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