pomegranate-db 0.1.0

package/dist/model/Model.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * Model base class.
+ *
+ * Each model instance represents a single database record.
+ * Models are schema-first: the schema defines columns, relations,
+ * and the TypeScript types are inferred from it.
+ *
+ * Usage:
+ *   class Post extends Model<typeof PostSchema> {
+ *     static schema = PostSchema;
+ *
+ *     publish = this.writer(async () => {
+ *       await this.update({ status: 'published' });
+ *     });
+ *   }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Model = void 0;
+exports.createRawRecord = createRawRecord;
+const Subject_1 = require("../observable/Subject");
+const utils_1 = require("../utils");
+class Model {
+    static schema;
+    /** The record id */
+    id;
+    /** Reference back to the owning collection */
+    collection;
+    /** The raw database row — ES private to avoid variance issues in generics */
+    #raw;
+    /**
+     * Observable for record changes.
+     * Typed as `BehaviorSubject<unknown>` to avoid TypeScript variance issues:
+     * `BehaviorSubject<this>` causes invariant `Set<Listener<T>>` mismatches
+     * when a subclass (e.g. Article) is assigned to `ModelStatic<Model>`.
+     * The public API (`observe()`) still returns `Observable<this>`.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    #changes$;
+    constructor(collection, raw) {
+        this.collection = collection;
+        this.#raw = raw;
+        this.id = raw.id;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.#changes$ = new Subject_1.BehaviorSubject(this);
+    }
+    // ─── Raw Access ────────────────────────────────────────────────────────
+    /** Get the current raw record */
+    get _rawRecord() {
+        return this.#raw;
+    }
+    /** Sync status of this record */
+    get syncStatus() {
+        return this.#raw._status;
+    }
+    /** Changed fields (comma-separated) */
+    get changedFields() {
+        return this.#raw._changed;
+    }
+    // ─── Field Accessors ──────────────────────────────────────────────────
+    /**
+     * Get a field value, converting from raw storage form.
+     */
+    getField(fieldName) {
+        const schema = this.constructor.schema;
+        const col = schema.columns.find((c) => c.fieldName === fieldName);
+        if (!col) {
+            // Check if it's a relation field name
+            const rel = schema.relations.find((r) => r.fieldName === fieldName);
+            if (rel && rel.kind === 'belongs_to') {
+                return this.#raw[rel.foreignKey];
+            }
+            throw new Error(`Unknown field "${fieldName}" on table "${schema.table}"`);
+        }
+        const rawValue = this.#raw[col.columnName];
+        return deserializeValue(col, rawValue);
+    }
+    /**
+     * Set field value(s) on the raw record (does NOT persist — internal use).
+     */
+    _setRaw(updates) {
+        this.#raw = { ...this.#raw, ...updates };
+        this.#changes$.next(this);
+    }
+    // ─── Observable ──────────────────────────────────────────────────────
+    /** Observe changes to this record */
+    observe() {
+        return this.#changes$;
+    }
+    /** Observe a specific field */
+    observeField(fieldName) {
+        return {
+            subscribe: (listener) => {
+                let lastValue = this.getField(fieldName);
+                // Emit initial value
+                listener(lastValue);
+                return this.#changes$.subscribe(() => {
+                    const newValue = this.getField(fieldName);
+                    if (newValue !== lastValue) {
+                        lastValue = newValue;
+                        listener(newValue);
+                    }
+                });
+            },
+        };
+    }
+    // ─── Mutations ────────────────────────────────────────────────────────
+    /**
+     * Update this record with a patch of field values.
+     * Must be called inside `db.write()`.
+     */
+    async update(patch) {
+        this.collection._getDatabase()._ensureInWriter('Model.update()');
+        const schema = this.constructor.schema;
+        const rawUpdates = {};
+        const changedColumns = [];
+        for (const [fieldName, value] of Object.entries(patch)) {
+            const col = schema.columns.find((c) => c.fieldName === fieldName);
+            if (col) {
+                if (col.isReadonly) {
+                    throw new Error(`Cannot update readonly field "${fieldName}"`);
+                }
+                rawUpdates[col.columnName] = serializeValue(col, value);
+                changedColumns.push(col.columnName);
+            }
+            else {
+                // Check belongs_to
+                const rel = schema.relations.find((r) => r.fieldName === fieldName && r.kind === 'belongs_to');
+                if (rel) {
+                    rawUpdates[rel.foreignKey] = value;
+                    changedColumns.push(rel.foreignKey);
+                }
+                else {
+                    throw new Error(`Unknown field "${fieldName}" on table "${schema.table}"`);
+                }
+            }
+        }
+        // Track changed columns for sync
+        const existingChanged = this.#raw._changed ? this.#raw._changed.split(',').filter(Boolean) : [];
+        const allChanged = [...new Set([...existingChanged, ...changedColumns])];
+        if (this.#raw._status === 'synced') {
+            rawUpdates._status = 'updated';
+        }
+        rawUpdates._changed = allChanged.join(',');
+        await this.collection._update(this.id, rawUpdates);
+        this._setRaw(rawUpdates);
+    }
+    /**
+     * Mark this record as deleted (soft delete for sync).
+     * Must be called inside `db.write()`.
+     */
+    async markAsDeleted() {
+        this.collection._getDatabase()._ensureInWriter('Model.markAsDeleted()');
+        await this.collection._delete(this.id);
+        this._setRaw({ _status: 'deleted' });
+    }
+    /**
+     * Permanently destroy this record.
+     * Must be called inside `db.write()`.
+     */
+    async destroyPermanently() {
+        this.collection._getDatabase()._ensureInWriter('Model.destroyPermanently()');
+        await this.collection._destroyPermanently(this.id);
+    }
+    // ─── Writer Helper ──────────────────────────────────────────────────
+    /**
+     * Create a bound writer method.
+     * The returned function, when called, will run inside the current write transaction.
+     */
+    writer(fn) {
+        return (...args) => {
+            // Writer just delegates — the caller must already be inside db.write()
+            return fn.apply(this, args);
+        };
+    }
+    // ─── Prepare for sync ───────────────────────────────────────────────
+    /**
+     * Return raw values suitable for the sync push payload.
+     */
+    toPushPayload() {
+        const { _status, _changed, ...rest } = this.#raw;
+        return rest;
+    }
+}
+exports.Model = Model;
+// ─── Serialization Helpers ─────────────────────────────────────────────────
+function serializeValue(col, value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    switch (col.type) {
+        case 'date':
+            return (0, utils_1.dateToTimestamp)(value);
+        case 'boolean':
+            return value ? 1 : 0;
+        default:
+            return value;
+    }
+}
+function deserializeValue(col, rawValue) {
+    if (rawValue === null || rawValue === undefined) {
+        return null;
+    }
+    switch (col.type) {
+        case 'date':
+            return (0, utils_1.timestampToDate)(rawValue);
+        case 'boolean':
+            return rawValue === 1 || rawValue === true;
+        default:
+            return rawValue;
+    }
+}
+// ─── Create a raw record from a schema + patch ────────────────────────────
+function createRawRecord(schema, patch, id) {
+    const raw = {
+        id: id ?? (0, utils_1.generateId)(),
+        _status: 'created',
+        _changed: '',
+    };
+    for (const col of schema.columns) {
+        const fieldName = col.fieldName;
+        if (fieldName in patch) {
+            raw[col.columnName] = serializeValue(col, patch[fieldName]);
+        }
+        else if (col.defaultValue !== undefined) {
+            raw[col.columnName] = serializeValue(col, col.defaultValue);
+        }
+        else if (col.isOptional) {
+            raw[col.columnName] = null;
+        }
+        else {
+            // Default zero-values
+            switch (col.type) {
+                case 'text':
+                    raw[col.columnName] = '';
+                    break;
+                case 'number':
+                    raw[col.columnName] = 0;
+                    break;
+                case 'boolean':
+                    raw[col.columnName] = 0;
+                    break;
+                case 'date':
+                    raw[col.columnName] = null;
+                    break;
+            }
+        }
+    }
+    return raw;
+}
+//# sourceMappingURL=Model.js.map

package/dist/model/index.d.ts

@@ -0,0 +1,2 @@
+export { Model, createRawRecord } from './Model';
+export type { ModelStatic, ModelCollectionRef, ModelDatabaseRef } from './Model';

package/dist/model/index.js

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

package/dist/observable/Subject.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Lightweight observable primitives.
+ *
+ * We avoid pulling in RxJS by implementing a minimal Subject/Observable
+ * that covers the use-cases we need: change notification for records,
+ * collections, and live queries.
+ */
+export type Listener<T> = (value: T) => void;
+export type Unsubscribe = () => void;
+export type TeardownFn = () => void;
+/**
+ * A minimal Observable that supports subscribe/unsubscribe.
+ */
+export interface Observable<T> {
+    subscribe(listener: Listener<T>): Unsubscribe;
+}
+/**
+ * A Subject is an Observable that you can push values into.
+ *
+ * NOTE: We use ES `#private` fields (not TypeScript `private`) so that the
+ * internal `Set<Listener<T>>` is invisible to the structural type checker.
+ * Without this, `Subject<Post>` is not assignable to `Subject<Model>` because
+ * `Set` is invariant — a classic generic-variance pitfall.
+ */
+export declare class Subject<T> implements Observable<T> {
+    #private;
+    constructor(initialValue?: T);
+    get lastValue(): T | undefined;
+    get hasValue(): boolean;
+    subscribe(listener: Listener<T>): Unsubscribe;
+    next(value: T): void;
+    get subscriberCount(): number;
+}
+/**
+ * A BehaviorSubject always has a current value and emits it to new subscribers.
+ */
+export declare class BehaviorSubject<T> extends Subject<T> {
+    constructor(initialValue: T);
+    get value(): T;
+}
+/**
+ * SharedObservable caches the latest result and replays to new subscribers.
+ * Runs a producer function when the first subscriber appears,
+ * and tears down when the last subscriber leaves.
+ */
+export declare class SharedObservable<T> implements Observable<T> {
+    private producer;
+    private subject;
+    private teardown;
+    constructor(producer: (emit: Listener<T>) => TeardownFn);
+    subscribe(listener: Listener<T>): Unsubscribe;
+}
+/**
+ * Utility: map an observable to a new observable.
+ */
+export declare function mapObservable<A, B>(source: Observable<A>, fn: (value: A) => B): Observable<B>;
+/**
+ * Utility: combine multiple observables into one that emits an array.
+ */
+export declare function combineObservables<T>(sources: Observable<T>[]): Observable<T[]>;

package/dist/observable/Subject.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Lightweight observable primitives.
+ *
+ * We avoid pulling in RxJS by implementing a minimal Subject/Observable
+ * that covers the use-cases we need: change notification for records,
+ * collections, and live queries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SharedObservable = exports.BehaviorSubject = exports.Subject = void 0;
+exports.mapObservable = mapObservable;
+exports.combineObservables = combineObservables;
+/**
+ * A Subject is an Observable that you can push values into.
+ *
+ * NOTE: We use ES `#private` fields (not TypeScript `private`) so that the
+ * internal `Set<Listener<T>>` is invisible to the structural type checker.
+ * Without this, `Subject<Post>` is not assignable to `Subject<Model>` because
+ * `Set` is invariant — a classic generic-variance pitfall.
+ */
+class Subject {
+    #listeners = new Set();
+    #lastValue;
+    #hasValue = false;
+    constructor(initialValue) {
+        if (arguments.length > 0) {
+            this.#lastValue = initialValue;
+            this.#hasValue = true;
+        }
+    }
+    get lastValue() {
+        return this.#lastValue;
+    }
+    get hasValue() {
+        return this.#hasValue;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        // Immediately emit last value if we have one
+        if (this.#hasValue) {
+            listener(this.#lastValue);
+        }
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    next(value) {
+        this.#lastValue = value;
+        this.#hasValue = true;
+        for (const listener of this.#listeners) {
+            listener(value);
+        }
+    }
+    get subscriberCount() {
+        return this.#listeners.size;
+    }
+}
+exports.Subject = Subject;
+/**
+ * A BehaviorSubject always has a current value and emits it to new subscribers.
+ */
+class BehaviorSubject extends Subject {
+    constructor(initialValue) {
+        super(initialValue);
+    }
+    get value() {
+        return this.lastValue;
+    }
+}
+exports.BehaviorSubject = BehaviorSubject;
+/**
+ * SharedObservable caches the latest result and replays to new subscribers.
+ * Runs a producer function when the first subscriber appears,
+ * and tears down when the last subscriber leaves.
+ */
+class SharedObservable {
+    producer;
+    subject = null;
+    teardown = null;
+    constructor(producer) {
+        this.producer = producer;
+    }
+    subscribe(listener) {
+        if (!this.subject) {
+            this.subject = new Subject();
+            this.teardown = this.producer((value) => this.subject.next(value));
+        }
+        const unsub = this.subject.subscribe(listener);
+        return () => {
+            unsub();
+            if (this.subject && this.subject.subscriberCount === 0) {
+                this.teardown?.();
+                this.teardown = null;
+                this.subject = null;
+            }
+        };
+    }
+}
+exports.SharedObservable = SharedObservable;
+/**
+ * Utility: map an observable to a new observable.
+ */
+function mapObservable(source, fn) {
+    return {
+        subscribe(listener) {
+            return source.subscribe((value) => listener(fn(value)));
+        },
+    };
+}
+/**
+ * Utility: combine multiple observables into one that emits an array.
+ */
+function combineObservables(sources) {
+    return {
+        subscribe(listener) {
+            const values = Array.from({ length: sources.length });
+            const received = new Set();
+            const unsubs = [];
+            sources.forEach((source, i) => {
+                unsubs.push(source.subscribe((value) => {
+                    values[i] = value;
+                    received.add(i);
+                    if (received.size === sources.length) {
+                        listener([...values]);
+                    }
+                }));
+            });
+            return () => unsubs.forEach((u) => u());
+        },
+    };
+}
+//# sourceMappingURL=Subject.js.map

package/dist/observable/index.d.ts

@@ -0,0 +1,2 @@
+export { Subject, BehaviorSubject, SharedObservable, mapObservable, combineObservables, } from './Subject';
+export type { Observable, Listener, Unsubscribe, TeardownFn } from './Subject';

package/dist/observable/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.combineObservables = exports.mapObservable = exports.SharedObservable = exports.BehaviorSubject = exports.Subject = void 0;
+var Subject_1 = require("./Subject");
+Object.defineProperty(exports, "Subject", { enumerable: true, get: function () { return Subject_1.Subject; } });
+Object.defineProperty(exports, "BehaviorSubject", { enumerable: true, get: function () { return Subject_1.BehaviorSubject; } });
+Object.defineProperty(exports, "SharedObservable", { enumerable: true, get: function () { return Subject_1.SharedObservable; } });
+Object.defineProperty(exports, "mapObservable", { enumerable: true, get: function () { return Subject_1.mapObservable; } });
+Object.defineProperty(exports, "combineObservables", { enumerable: true, get: function () { return Subject_1.combineObservables; } });
+//# sourceMappingURL=index.js.map

package/dist/query/QueryBuilder.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Query builder — fluent API for constructing QueryDescriptors.
+ *
+ * Usage:
+ *   const q = new QueryBuilder('posts')
+ *     .where('status', 'eq', 'published')
+ *     .where('createdAt', 'gt', someDate)
+ *     .orderBy('createdAt', 'desc')
+ *     .limit(20)
+ *     .build();
+ */
+import type { QueryDescriptor, ComparisonOperator, SortOrder } from './types';
+export declare class QueryBuilder {
+    private _table;
+    private _conditions;
+    private _orderBy;
+    private _limit?;
+    private _offset?;
+    private _joins;
+    constructor(table: string);
+    /** Add a WHERE condition */
+    where(column: string, value: unknown): this;
+    where(column: string, operator: ComparisonOperator, value: unknown): this;
+    /** WHERE column IS NULL */
+    whereNull(column: string): this;
+    /** WHERE column IS NOT NULL */
+    whereNotNull(column: string): this;
+    /** WHERE column IN (...values) */
+    whereIn(column: string, values: unknown[]): this;
+    /** WHERE column BETWEEN low AND high */
+    whereBetween(column: string, low: unknown, high: unknown): this;
+    /** WHERE column LIKE pattern */
+    whereLike(column: string, pattern: string): this;
+    /** Combine conditions with AND */
+    and(builder: (qb: QueryBuilder) => void): this;
+    /** Combine conditions with OR */
+    or(builder: (qb: QueryBuilder) => void): this;
+    /** Add ORDER BY */
+    orderBy(column: string, order?: SortOrder): this;
+    /** Set LIMIT */
+    limit(n: number): this;
+    /** Set OFFSET */
+    offset(n: number): this;
+    /** Add a JOIN clause */
+    join(table: string, leftColumn: string, rightColumn: string): this;
+    /** Build the final query descriptor */
+    build(): QueryDescriptor;
+    /** Clone this builder for forking */
+    clone(): QueryBuilder;
+}
+export declare function query(table: string): QueryBuilder;

package/dist/query/QueryBuilder.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Query builder — fluent API for constructing QueryDescriptors.
+ *
+ * Usage:
+ *   const q = new QueryBuilder('posts')
+ *     .where('status', 'eq', 'published')
+ *     .where('createdAt', 'gt', someDate)
+ *     .orderBy('createdAt', 'desc')
+ *     .limit(20)
+ *     .build();
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBuilder = void 0;
+exports.query = query;
+class QueryBuilder {
+    _table;
+    _conditions = [];
+    _orderBy = [];
+    _limit;
+    _offset;
+    _joins = [];
+    constructor(table) {
+        this._table = table;
+    }
+    where(column, operatorOrValue, maybeValue) {
+        let operator;
+        let value;
+        if (maybeValue === undefined) {
+            operator = 'eq';
+            value = operatorOrValue;
+        }
+        else {
+            operator = operatorOrValue;
+            value = maybeValue;
+        }
+        const clause = {
+            type: 'where',
+            column,
+            operator,
+            value,
+        };
+        this._conditions.push(clause);
+        return this;
+    }
+    /** WHERE column IS NULL */
+    whereNull(column) {
+        this._conditions.push({
+            type: 'where',
+            column,
+            operator: 'isNull',
+            value: null,
+        });
+        return this;
+    }
+    /** WHERE column IS NOT NULL */
+    whereNotNull(column) {
+        this._conditions.push({
+            type: 'where',
+            column,
+            operator: 'isNotNull',
+            value: null,
+        });
+        return this;
+    }
+    /** WHERE column IN (...values) */
+    whereIn(column, values) {
+        this._conditions.push({
+            type: 'where',
+            column,
+            operator: 'in',
+            value: values,
+        });
+        return this;
+    }
+    /** WHERE column BETWEEN low AND high */
+    whereBetween(column, low, high) {
+        this._conditions.push({
+            type: 'where',
+            column,
+            operator: 'between',
+            value: [low, high],
+        });
+        return this;
+    }
+    /** WHERE column LIKE pattern */
+    whereLike(column, pattern) {
+        this._conditions.push({
+            type: 'where',
+            column,
+            operator: 'like',
+            value: pattern,
+        });
+        return this;
+    }
+    /** Combine conditions with AND */
+    and(builder) {
+        const sub = new QueryBuilder(this._table);
+        builder(sub);
+        const andClause = {
+            type: 'and',
+            conditions: sub._conditions,
+        };
+        this._conditions.push(andClause);
+        return this;
+    }
+    /** Combine conditions with OR */
+    or(builder) {
+        const sub = new QueryBuilder(this._table);
+        builder(sub);
+        const orClause = {
+            type: 'or',
+            conditions: sub._conditions,
+        };
+        this._conditions.push(orClause);
+        return this;
+    }
+    /** Add ORDER BY */
+    orderBy(column, order = 'asc') {
+        this._orderBy.push({ column, order });
+        return this;
+    }
+    /** Set LIMIT */
+    limit(n) {
+        this._limit = n;
+        return this;
+    }
+    /** Set OFFSET */
+    offset(n) {
+        this._offset = n;
+        return this;
+    }
+    /** Add a JOIN clause */
+    join(table, leftColumn, rightColumn) {
+        this._joins.push({ table, leftColumn, rightColumn });
+        return this;
+    }
+    /** Build the final query descriptor */
+    build() {
+        return Object.freeze({
+            table: this._table,
+            conditions: Object.freeze([...this._conditions]),
+            orderBy: Object.freeze([...this._orderBy]),
+            limit: this._limit,
+            offset: this._offset,
+            joins: Object.freeze([...this._joins]),
+        });
+    }
+    /** Clone this builder for forking */
+    clone() {
+        const qb = new QueryBuilder(this._table);
+        qb._conditions = [...this._conditions];
+        qb._orderBy = [...this._orderBy];
+        qb._limit = this._limit;
+        qb._offset = this._offset;
+        qb._joins = [...this._joins];
+        return qb;
+    }
+}
+exports.QueryBuilder = QueryBuilder;
+// ─── Convenience factory ───────────────────────────────────────────────────
+function query(table) {
+    return new QueryBuilder(table);
+}
+//# sourceMappingURL=QueryBuilder.js.map

package/dist/query/index.d.ts

@@ -0,0 +1,2 @@
+export { QueryBuilder, query } from './QueryBuilder';
+export type { ComparisonOperator, WhereClause, AndClause, OrClause, NotClause, Condition, SortOrder, OrderByClause, JoinClause, QueryDescriptor, SearchDescriptor, BatchOperation, BatchOperationType, } from './types';