pomegranate-db 0.1.0

package/dist/collection/Collection.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Collection — manages all records for a single table/model.
+ *
+ * Collections provide CRUD operations, query building, record caching,
+ * and change notification. Each Collection is associated with one Model class.
+ */
+import type { ModelSchema, RawRecord } from '../schema/types';
+import type { ModelStatic, ModelCollectionRef, ModelDatabaseRef, Model } from '../model/Model';
+import { QueryBuilder } from '../query/QueryBuilder';
+import type { QueryDescriptor } from '../query/types';
+import type { Observable } from '../observable/Subject';
+import type { StorageAdapter } from '../adapters/types';
+export type CollectionChangeType = 'created' | 'updated' | 'deleted';
+export interface CollectionChange {
+    readonly type: CollectionChangeType;
+    readonly record: Model;
+}
+export declare class Collection<M extends Model = Model> implements ModelCollectionRef {
+    readonly table: string;
+    private _modelClass;
+    private _schema;
+    private _database;
+    /** In-memory cache of instantiated records by ID */
+    private _cache;
+    /** Emits whenever the collection changes */
+    private _changes$;
+    constructor(database: ModelDatabaseRef & {
+        _adapter: StorageAdapter;
+    }, modelClass: ModelStatic);
+    get schema(): ModelSchema;
+    /**
+     * Create a new record.
+     * Must be called inside `db.write()`.
+     */
+    create(patch: Record<string, unknown>): Promise<M>;
+    /**
+     * Find a record by ID.
+     * Returns the cached instance if available.
+     */
+    findById(id: string): Promise<M | null>;
+    /**
+     * Find a record by ID or throw.
+     */
+    findByIdOrFail(id: string): Promise<M>;
+    /**
+     * Query records using the fluent QueryBuilder.
+     */
+    query(): QueryBuilder;
+    query(fn: (qb: QueryBuilder) => void): QueryBuilder;
+    /**
+     * Execute a query and return model instances.
+     */
+    fetch(queryOrBuilder: QueryDescriptor | QueryBuilder): Promise<M[]>;
+    /**
+     * Count records matching a query.
+     */
+    count(queryOrBuilder?: QueryDescriptor | QueryBuilder): Promise<number>;
+    /**
+     * Full-text search.
+     */
+    search(opts: {
+        term: string;
+        fields: string[];
+        limit?: number;
+        offset?: number;
+        extend?: (qb: QueryBuilder) => void;
+        orderBy?: Record<string, 'asc' | 'desc'>;
+    }): Promise<{
+        records: M[];
+        total: number;
+    }>;
+    /**
+     * Observe all changes to this collection.
+     */
+    get changes$(): Observable<CollectionChange>;
+    /**
+     * Create a live query that re-runs whenever the collection changes.
+     * Returns an observable of record arrays.
+     */
+    observeQuery(queryOrBuilder: QueryDescriptor | QueryBuilder): Observable<M[]>;
+    /**
+     * Observe a single record by ID.
+     */
+    observeById(id: string): Observable<M | null>;
+    /**
+     * Observe a count matching a query.
+     */
+    observeCount(queryOrBuilder?: QueryDescriptor | QueryBuilder): Observable<number>;
+    _update(id: string, rawUpdates: Partial<RawRecord>): Promise<void>;
+    _delete(id: string): Promise<void>;
+    _destroyPermanently(id: string): Promise<void>;
+    _getDatabase(): ModelDatabaseRef;
+    /** Create a Model instance from a raw record */
+    private _instantiate;
+    /** Get-or-create a Model instance from a raw record (cache-aware) */
+    private _materialize;
+    /** Clear the cache — used during reset or sync */
+    _clearCache(): void;
+    /** Directly add a raw record to cache (used during sync) */
+    _cacheRaw(raw: RawRecord): M;
+    /** Notify external change (used by sync/batch) */
+    _notifyChange(type: CollectionChangeType, record: Model): void;
+}

package/dist/collection/Collection.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * Collection — manages all records for a single table/model.
+ *
+ * Collections provide CRUD operations, query building, record caching,
+ * and change notification. Each Collection is associated with one Model class.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Collection = void 0;
+const Model_1 = require("../model/Model");
+const QueryBuilder_1 = require("../query/QueryBuilder");
+const Subject_1 = require("../observable/Subject");
+const Subject_2 = require("../observable/Subject");
+// ─── Collection class ──────────────────────────────────────────────────────
+class Collection {
+    table;
+    _modelClass;
+    _schema;
+    _database;
+    /** In-memory cache of instantiated records by ID */
+    _cache = new Map();
+    /** Emits whenever the collection changes */
+    _changes$ = new Subject_1.Subject();
+    constructor(database, modelClass) {
+        this._database = database;
+        this._modelClass = modelClass;
+        this._schema = modelClass.schema;
+        this.table = this._schema.table;
+    }
+    // ─── Schema access ──────────────────────────────────────────────────
+    get schema() {
+        return this._schema;
+    }
+    // ─── CRUD ──────────────────────────────────────────────────────────
+    /**
+     * Create a new record.
+     * Must be called inside `db.write()`.
+     */
+    async create(patch) {
+        this._database._ensureInWriter('Collection.create()');
+        const raw = (0, Model_1.createRawRecord)(this._schema, patch);
+        await this._database._adapter.insert(this.table, raw);
+        const record = this._instantiate(raw);
+        this._cache.set(record.id, record);
+        this._changes$.next({ type: 'created', record });
+        return record;
+    }
+    /**
+     * Find a record by ID.
+     * Returns the cached instance if available.
+     */
+    async findById(id) {
+        const cached = this._cache.get(id);
+        if (cached)
+            return cached;
+        const raw = await this._database._adapter.findById(this.table, id);
+        if (!raw)
+            return null;
+        const record = this._instantiate(raw);
+        this._cache.set(id, record);
+        return record;
+    }
+    /**
+     * Find a record by ID or throw.
+     */
+    async findByIdOrFail(id) {
+        const record = await this.findById(id);
+        if (!record) {
+            throw new Error(`Record not found: ${this.table}/${id}`);
+        }
+        return record;
+    }
+    query(fn) {
+        const qb = new QueryBuilder_1.QueryBuilder(this.table);
+        // Automatically exclude soft-deleted records
+        qb.where('_status', 'neq', 'deleted');
+        if (fn)
+            fn(qb);
+        return qb;
+    }
+    /**
+     * Execute a query and return model instances.
+     */
+    async fetch(queryOrBuilder) {
+        const descriptor = queryOrBuilder instanceof QueryBuilder_1.QueryBuilder ? queryOrBuilder.build() : queryOrBuilder;
+        const raws = await this._database._adapter.find(descriptor);
+        return raws.map((raw) => this._materialize(raw));
+    }
+    /**
+     * Count records matching a query.
+     */
+    async count(queryOrBuilder) {
+        const descriptor = queryOrBuilder
+            ? (queryOrBuilder instanceof QueryBuilder_1.QueryBuilder
+                ? queryOrBuilder.build()
+                : queryOrBuilder)
+            : this.query().build();
+        return this._database._adapter.count(descriptor);
+    }
+    /**
+     * Full-text search.
+     */
+    async search(opts) {
+        const qb = this.query();
+        if (opts.extend)
+            opts.extend(qb);
+        const orderByEntries = opts.orderBy
+            ? Object.entries(opts.orderBy).map(([column, order]) => ({ column, order }))
+            : [];
+        const descriptor = {
+            table: this.table,
+            term: opts.term,
+            fields: opts.fields,
+            conditions: qb.build().conditions,
+            orderBy: orderByEntries,
+            limit: opts.limit ?? 50,
+            offset: opts.offset ?? 0,
+        };
+        const result = await this._database._adapter.search(descriptor);
+        const records = result.records.map((raw) => this._materialize(raw));
+        return { records, total: result.total };
+    }
+    // ─── Observe ──────────────────────────────────────────────────────
+    /**
+     * Observe all changes to this collection.
+     */
+    get changes$() {
+        return this._changes$;
+    }
+    /**
+     * Create a live query that re-runs whenever the collection changes.
+     * Returns an observable of record arrays.
+     */
+    observeQuery(queryOrBuilder) {
+        const descriptor = queryOrBuilder instanceof QueryBuilder_1.QueryBuilder ? queryOrBuilder.build() : queryOrBuilder;
+        return new Subject_2.SharedObservable((emit) => {
+            // Initial fetch
+            this._database._adapter.find(descriptor).then((raws) => {
+                emit(raws.map((raw) => this._materialize(raw)));
+            });
+            // Re-fetch on any collection change
+            const unsub = this._changes$.subscribe(async () => {
+                const raws = await this._database._adapter.find(descriptor);
+                emit(raws.map((raw) => this._materialize(raw)));
+            });
+            return unsub;
+        });
+    }
+    /**
+     * Observe a single record by ID.
+     */
+    observeById(id) {
+        return new Subject_2.SharedObservable((emit) => {
+            // Initial fetch
+            this.findById(id).then(emit);
+            // Re-check on changes
+            const unsub = this._changes$.subscribe(async (change) => {
+                if (change.record.id === id) {
+                    if (change.type === 'deleted') {
+                        emit(null);
+                    }
+                    else {
+                        emit(await this.findById(id));
+                    }
+                }
+            });
+            return unsub;
+        });
+    }
+    /**
+     * Observe a count matching a query.
+     */
+    observeCount(queryOrBuilder) {
+        const descriptor = queryOrBuilder
+            ? (queryOrBuilder instanceof QueryBuilder_1.QueryBuilder
+                ? queryOrBuilder.build()
+                : queryOrBuilder)
+            : this.query().build();
+        return new Subject_2.SharedObservable((emit) => {
+            this._database._adapter.count(descriptor).then(emit);
+            const unsub = this._changes$.subscribe(async () => {
+                emit(await this._database._adapter.count(descriptor));
+            });
+            return unsub;
+        });
+    }
+    // ─── Internal (called by Model) ────────────────────────────────────
+    async _update(id, rawUpdates) {
+        const existing = this._cache.get(id);
+        if (!existing)
+            throw new Error(`Cannot update: record ${id} not in cache`);
+        const merged = { ...existing._rawRecord, ...rawUpdates };
+        await this._database._adapter.update(this.table, merged);
+        this._changes$.next({ type: 'updated', record: existing });
+    }
+    async _delete(id) {
+        await this._database._adapter.markAsDeleted(this.table, id);
+        const record = this._cache.get(id);
+        if (record) {
+            this._changes$.next({ type: 'deleted', record });
+        }
+    }
+    async _destroyPermanently(id) {
+        await this._database._adapter.destroyPermanently(this.table, id);
+        const record = this._cache.get(id);
+        this._cache.delete(id);
+        if (record) {
+            this._changes$.next({ type: 'deleted', record });
+        }
+    }
+    _getDatabase() {
+        return this._database;
+    }
+    // ─── Internal helpers ──────────────────────────────────────────────
+    /** Create a Model instance from a raw record */
+    _instantiate(raw) {
+        return new this._modelClass(this, raw);
+    }
+    /** Get-or-create a Model instance from a raw record (cache-aware) */
+    _materialize(raw) {
+        const existing = this._cache.get(raw.id);
+        if (existing) {
+            // Refresh the raw data
+            existing._setRaw(raw);
+            return existing;
+        }
+        const record = this._instantiate(raw);
+        this._cache.set(raw.id, record);
+        return record;
+    }
+    /** Clear the cache — used during reset or sync */
+    _clearCache() {
+        this._cache.clear();
+    }
+    /** Directly add a raw record to cache (used during sync) */
+    _cacheRaw(raw) {
+        return this._materialize(raw);
+    }
+    /** Notify external change (used by sync/batch) */
+    _notifyChange(type, record) {
+        this._changes$.next({ type, record });
+    }
+}
+exports.Collection = Collection;
+//# sourceMappingURL=Collection.js.map

package/dist/collection/index.d.ts

@@ -0,0 +1,2 @@
+export { Collection } from './Collection';
+export type { CollectionChangeType, CollectionChange } from './Collection';

package/dist/collection/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Collection = void 0;
+var Collection_1 = require("./Collection");
+Object.defineProperty(exports, "Collection", { enumerable: true, get: function () { return Collection_1.Collection; } });
+//# sourceMappingURL=index.js.map

package/dist/database/Database.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Database — the top-level entry point.
+ *
+ * The Database owns the adapter, manages collections, and provides
+ * the `write()` transactional boundary.
+ *
+ * Usage:
+ *   const db = new Database({
+ *     adapter: new SQLiteAdapter({ databaseName: 'app.db' }),
+ *     models: [Post, User, Comment],
+ *   });
+ *
+ *   await db.write(async () => {
+ *     await db.get(Post).create({ title: 'Hello' });
+ *   });
+ */
+import type { StorageAdapter } from '../adapters/types';
+import type { EncryptionConfig } from '../adapters/types';
+import type { ModelSchema, RawRecord } from '../schema/types';
+import { Collection } from '../collection/Collection';
+import type { Model } from '../model/Model';
+import type { ModelStatic, ModelDatabaseRef } from '../model/Model';
+import type { BatchOperation } from '../query/types';
+import type { Observable } from '../observable/Subject';
+export interface DatabaseConfig {
+    readonly adapter: StorageAdapter;
+    readonly models: ModelStatic[];
+    readonly schemaVersion?: number;
+    readonly encryption?: EncryptionConfig;
+}
+export type DatabaseEvent = {
+    type: 'initialized';
+} | {
+    type: 'write_started';
+} | {
+    type: 'write_completed';
+} | {
+    type: 'sync_started';
+} | {
+    type: 'sync_completed';
+} | {
+    type: 'reset';
+};
+export declare class Database implements ModelDatabaseRef {
+    private config;
+    readonly _adapter: StorageAdapter;
+    private _collections;
+    private _modelMap;
+    private _initialized;
+    private _isInWriter;
+    private _writeQueue;
+    private _isProcessingQueue;
+    private _events$;
+    private _schemaVersion;
+    constructor(config: DatabaseConfig);
+    /**
+     * Initialize the database. Must be called before any operations.
+     * Creates tables if they don't exist.
+     */
+    initialize(): Promise<void>;
+    private _buildDatabaseSchema;
+    /**
+     * Get the collection for a model class.
+     */
+    get<M extends Model>(modelClass: ModelStatic<ModelSchema>): Collection<M>;
+    /**
+     * Get a collection by table name.
+     */
+    collection(table: string): Collection;
+    /**
+     * All registered collections.
+     */
+    get collections(): Collection[];
+    /**
+     * Execute a write transaction.
+     *
+     * All mutations (create, update, delete) must happen inside a write() call.
+     * Write calls are serialized — only one runs at a time.
+     */
+    write<T>(fn: () => Promise<T>): Promise<T>;
+    private _processWriteQueue;
+    /**
+     * @internal Throw if not inside a writer.
+     */
+    _ensureInWriter(action: string): void;
+    /**
+     * Execute a batch of operations atomically.
+     * Must be called inside `db.write()`.
+     */
+    batch(operations: BatchOperation[]): Promise<void>;
+    /** @internal used by Model */
+    _batch(operations: BatchOperation[]): Promise<void>;
+    /**
+     * Run a sync cycle.
+     * See sync/index.ts for the full implementation.
+     */
+    sync(opts: {
+        pullChanges: (params: {
+            lastPulledAt: number | null;
+        }) => Promise<{
+            changes: Record<string, {
+                created: RawRecord[];
+                updated: RawRecord[];
+                deleted: string[];
+            }>;
+            timestamp: number;
+        }>;
+        pushChanges: (params: {
+            changes: Record<string, {
+                created: RawRecord[];
+                updated: RawRecord[];
+                deleted: string[];
+            }>;
+            lastPulledAt: number;
+        }) => Promise<void>;
+    }): Promise<void>;
+    /**
+     * Completely reset the database — drops all data.
+     */
+    reset(): Promise<void>;
+    get events$(): Observable<DatabaseEvent>;
+    close(): Promise<void>;
+    private _ensureInitialized;
+    /**
+     * The tables this database manages.
+     */
+    get tables(): string[];
+}