@edge-base/core 0.1.1

package/dist/table.js

@@ -0,0 +1,734 @@
+/**
+ * Collection client with query builder and CRUD operations
+ *: filter tuple format
+ *: OR filter (.or() chaining)
+ *: increment, deleteField
+ *: upsert
+ *: count
+ *: batch-by-filter
+ *: batch operations
+ * #136: /api/db/{namespace}/tables/{name} URL scheme
+ *
+ * All HTTP calls delegate to Generated Core (api-core.ts).
+ * No hardcoded API paths — the core is the single source of truth.
+ */
+import { ApiPaths } from './generated/api-core.js';
+import { serializeFieldOps } from './field-ops.js';
+import { EdgeBaseError } from './errors.js';
+// ─── Database Live Channel Builder ───
+/**
+ * Build the database-live channel for a DB table. (§10)
+ *   Static DB:  dblive:shared:posts
+ *   Dynamic DB: dblive:workspace:ws-456:documents
+ *   Single doc: dblive:shared:posts:{docId}
+ */
+function buildDatabaseLiveChannel(namespace, instanceId, tableName, docId) {
+    const base = instanceId
+        ? `dblive:${namespace}:${instanceId}:${tableName}`
+        : `dblive:${namespace}:${tableName}`;
+    return docId ? `${base}:${docId}` : base;
+}
+function evaluateFilterCondition(fieldValue, operator, expected) {
+    switch (operator) {
+        case '==':
+            return fieldValue === expected;
+        case '!=':
+            return fieldValue !== expected;
+        case '<':
+            return fieldValue < expected;
+        case '>':
+            return fieldValue > expected;
+        case '<=':
+            return fieldValue <= expected;
+        case '>=':
+            return fieldValue >= expected;
+        case 'contains':
+            if (typeof fieldValue === 'string')
+                return fieldValue.includes(expected);
+            if (Array.isArray(fieldValue))
+                return fieldValue.includes(expected);
+            return false;
+        case 'contains-any':
+            if (!Array.isArray(fieldValue) || !Array.isArray(expected))
+                return false;
+            return expected.some((value) => fieldValue.includes(value));
+        case 'in':
+            return Array.isArray(expected) ? expected.includes(fieldValue) : false;
+        case 'not in':
+            return Array.isArray(expected) ? !expected.includes(fieldValue) : true;
+        default:
+            return false;
+    }
+}
+function matchesAllFilters(data, filters, filterMatchFn) {
+    if (filters.length === 0)
+        return true;
+    if (filterMatchFn) {
+        return filterMatchFn(data, filters);
+    }
+    return filters.every(([field, operator, value]) => evaluateFilterCondition(data[field], operator, value));
+}
+function matchesAnyFilter(data, filters, filterMatchFn) {
+    if (filters.length === 0)
+        return true;
+    if (filterMatchFn) {
+        return filters.some((filter) => filterMatchFn(data, [filter]));
+    }
+    return filters.some(([field, operator, value]) => evaluateFilterCondition(data[field], operator, value));
+}
+function matchesSnapshotFilters(data, filters, orFilters, filterMatchFn) {
+    if (!matchesAllFilters(data, filters, filterMatchFn)) {
+        return false;
+    }
+    if (orFilters.length === 0) {
+        return true;
+    }
+    return matchesAnyFilter(data, orFilters, filterMatchFn);
+}
+// ─── Core dispatch helpers ───
+/** Call the correct generated core method based on static vs dynamic DB. */
+function coreGet(core, method, namespace, instanceId, table, args) {
+    const tablePath = encodeURIComponent(table);
+    const q = args.query ?? {};
+    if (instanceId) {
+        // Dynamic DB
+        switch (method) {
+            case 'list': return core.dbListRecords(namespace, instanceId, tablePath, q);
+            case 'get': return core.dbGetRecord(namespace, instanceId, tablePath, args.id, q);
+            case 'count': return core.dbCountRecords(namespace, instanceId, tablePath, q);
+            case 'search': return core.dbSearchRecords(namespace, instanceId, tablePath, q);
+        }
+    }
+    // Single-instance DB
+    switch (method) {
+        case 'list': return core.dbSingleListRecords(namespace, tablePath, q);
+        case 'get': return core.dbSingleGetRecord(namespace, tablePath, args.id, q);
+        case 'count': return core.dbSingleCountRecords(namespace, tablePath, q);
+        case 'search': return core.dbSingleSearchRecords(namespace, tablePath, q);
+    }
+}
+function coreInsert(core, namespace, instanceId, table, body, query = {}) {
+    const tablePath = encodeURIComponent(table);
+    if (instanceId) {
+        return core.dbInsertRecord(namespace, instanceId, tablePath, body, query);
+    }
+    return core.dbSingleInsertRecord(namespace, tablePath, body, query);
+}
+function coreUpdate(core, namespace, instanceId, table, id, body) {
+    const tablePath = encodeURIComponent(table);
+    if (instanceId) {
+        return core.dbUpdateRecord(namespace, instanceId, tablePath, id, body);
+    }
+    return core.dbSingleUpdateRecord(namespace, tablePath, id, body);
+}
+function coreDelete(core, namespace, instanceId, table, id) {
+    const tablePath = encodeURIComponent(table);
+    if (instanceId) {
+        return core.dbDeleteRecord(namespace, instanceId, tablePath, id);
+    }
+    return core.dbSingleDeleteRecord(namespace, tablePath, id);
+}
+function coreBatch(core, namespace, instanceId, table, body, query = {}) {
+    const tablePath = encodeURIComponent(table);
+    if (instanceId) {
+        return core.dbBatchRecords(namespace, instanceId, tablePath, body, query);
+    }
+    return core.dbSingleBatchRecords(namespace, tablePath, body, query);
+}
+function coreBatchByFilter(core, namespace, instanceId, table, body, query = {}) {
+    const tablePath = encodeURIComponent(table);
+    if (instanceId) {
+        return core.dbBatchByFilter(namespace, instanceId, tablePath, body, query);
+    }
+    return core.dbSingleBatchByFilter(namespace, tablePath, body, query);
+}
+// ─── DocRef ───
+/**
+ * Document reference for single-record operations.
+ * Created via `client.db('shared').table('posts').doc('post-1')`
+ */
+export class DocRef {
+    core;
+    namespace;
+    instanceId;
+    tableName;
+    id;
+    databaseLiveClient;
+    filterMatchFn;
+    constructor(core, namespace, instanceId, tableName, id, databaseLiveClient, filterMatchFn) {
+        this.core = core;
+        this.namespace = namespace;
+        this.instanceId = instanceId;
+        this.tableName = tableName;
+        this.id = id;
+        this.databaseLiveClient = databaseLiveClient;
+        this.filterMatchFn = filterMatchFn;
+    }
+    /** Get a single record */
+    async get() {
+        return coreGet(this.core, 'get', this.namespace, this.instanceId, this.tableName, { id: this.id, query: {} });
+    }
+    /** Update a record (supports increment, deleteField) */
+    async update(data) {
+        const serialized = serializeFieldOps(data);
+        return coreUpdate(this.core, this.namespace, this.instanceId, this.tableName, this.id, serialized);
+    }
+    /** Delete a record */
+    async delete() {
+        await coreDelete(this.core, this.namespace, this.instanceId, this.tableName, this.id);
+    }
+    /**
+     * Subscribe to database-live changes for this document.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * const unsub = client.db('shared').table('posts').doc('post-1').onSnapshot((post) => {
+     *   console.log('Post updated:', post);
+     * });
+     */
+    onSnapshot(callback) {
+        if (!this.databaseLiveClient) {
+            throw new EdgeBaseError(500, 'IDatabaseLiveSubscriber not available');
+        }
+        const channel = buildDatabaseLiveChannel(this.namespace, this.instanceId, this.tableName, this.id);
+        return this.databaseLiveClient.onSnapshot(channel, (change) => {
+            callback(change.data, change);
+        });
+    }
+}
+// ─── TableRef ───
+/**
+ * Collection reference with query builder (immutable chaining).
+ * Created via `client.db('shared').table('posts')`
+ *
+ * @example
+ * const result = await client.db('shared').table('posts')
+ *   .where('status', '==', 'published')
+ *   .orderBy('createdAt', 'desc')
+ *   .limit(20)
+ *   .getList();
+ */
+export class TableRef {
+    core;
+    name;
+    databaseLiveClient;
+    filterMatchFn;
+    namespace;
+    instanceId;
+    _httpClient;
+    filters = [];
+    orFilters = []; //: OR conditions
+    sorts = [];
+    limitValue;
+    offsetValue;
+    pageValue;
+    searchQuery;
+    afterCursor;
+    beforeCursor;
+    constructor(core, 
+    /** Table name within the DB block */
+    name, databaseLiveClient, filterMatchFn, 
+    /** DB namespace: 'shared' | 'workspace' | 'user' | ... (§2) */
+    namespace = 'shared', 
+    /** DB instance ID for dynamic DOs (e.g. 'ws-456'). Omit for static DBs. */
+    instanceId, 
+    /**
+     * Raw HttpClient — only used for sql() which is admin-only and not in client core.
+     * TODO: remove once admin core is wired.
+     */
+    _httpClient) {
+        this.core = core;
+        this.name = name;
+        this.databaseLiveClient = databaseLiveClient;
+        this.filterMatchFn = filterMatchFn;
+        this.namespace = namespace;
+        this.instanceId = instanceId;
+        this._httpClient = _httpClient;
+    }
+    /** Create a clone with current state (for immutable chaining) */
+    clone() {
+        const ref = new TableRef(this.core, this.name, this.databaseLiveClient, this.filterMatchFn, this.namespace, this.instanceId, this._httpClient);
+        ref.filters = [...this.filters];
+        ref.orFilters = [...this.orFilters];
+        ref.sorts = [...this.sorts];
+        ref.limitValue = this.limitValue;
+        ref.offsetValue = this.offsetValue;
+        ref.pageValue = this.pageValue;
+        ref.searchQuery = this.searchQuery;
+        ref.afterCursor = this.afterCursor;
+        ref.beforeCursor = this.beforeCursor;
+        return ref;
+    }
+    /** Add a filter condition */
+    where(field, operator, value) {
+        const ref = this.clone();
+        ref.filters.push([field, operator, value]);
+        return ref;
+    }
+    /**
+     * Add OR conditions.
+     * Conditions inside the builder are joined with OR.
+     *
+     * @example
+     * client.db('shared').table('posts')
+     *   .where('createdAt', '>', '2025-01-01') // AND
+     *   .or(q => q.where('status', '==', 'draft').where('status', '==', 'archived')) // OR
+     *   .getList()
+     */
+    or(builder) {
+        const ref = this.clone();
+        const orBuilder = new OrBuilder();
+        builder(orBuilder);
+        ref.orFilters = [...ref.orFilters, ...orBuilder.getFilters()];
+        return ref;
+    }
+    /** Add sort order (supports multiple — chained calls accumulate) */
+    orderBy(field, direction = 'asc') {
+        const ref = this.clone();
+        ref.sorts.push([field, direction]);
+        return ref;
+    }
+    /** Set result limit */
+    limit(n) {
+        const ref = this.clone();
+        ref.limitValue = n;
+        return ref;
+    }
+    /** Set result offset */
+    offset(n) {
+        const ref = this.clone();
+        ref.offsetValue = n;
+        return ref;
+    }
+    /** Set page number for offset pagination (1-based) */
+    page(n) {
+        const ref = this.clone();
+        ref.pageValue = n;
+        return ref;
+    }
+    /** Set full-text search query */
+    search(query) {
+        const ref = this.clone();
+        ref.searchQuery = query;
+        return ref;
+    }
+    /**
+     * Set cursor for forward pagination.
+     * Fetches records with id > cursor. Mutually exclusive with page()/offset().
+     */
+    after(cursor) {
+        const ref = this.clone();
+        ref.afterCursor = cursor;
+        ref.beforeCursor = undefined;
+        return ref;
+    }
+    /**
+     * Set cursor for backward pagination.
+     * Fetches records with id < cursor. Mutually exclusive with page()/offset().
+     */
+    before(cursor) {
+        const ref = this.clone();
+        ref.beforeCursor = cursor;
+        ref.afterCursor = undefined;
+        return ref;
+    }
+    /** Build query parameters from current state */
+    buildQueryParams() {
+        //: offset/cursor mutual exclusion
+        const hasCursor = this.afterCursor !== undefined || this.beforeCursor !== undefined;
+        const hasOffset = this.offsetValue !== undefined || this.pageValue !== undefined;
+        if (hasCursor && hasOffset) {
+            throw new EdgeBaseError(400, 'Cannot use page()/offset() with after()/before() — choose offset or cursor pagination');
+        }
+        const query = {};
+        if (this.filters.length > 0) {
+            query.filter = JSON.stringify(this.filters);
+        }
+        if (this.orFilters.length > 0) {
+            query.orFilter = JSON.stringify(this.orFilters);
+        }
+        if (this.sorts.length > 0) {
+            query.sort = this.sorts.map(([f, d]) => `${f}:${d}`).join(',');
+        }
+        if (this.limitValue !== undefined) {
+            query.limit = String(this.limitValue);
+        }
+        if (this.pageValue !== undefined) {
+            query.page = String(this.pageValue);
+        }
+        if (this.offsetValue !== undefined) {
+            query.offset = String(this.offsetValue);
+        }
+        if (this.afterCursor !== undefined) {
+            query.after = this.afterCursor;
+        }
+        if (this.beforeCursor !== undefined) {
+            query.before = this.beforeCursor;
+        }
+        return query;
+    }
+    /** Get a document reference for single-record operations */
+    doc(id) {
+        return new DocRef(this.core, this.namespace, this.instanceId, this.name, id, this.databaseLiveClient, this.filterMatchFn);
+    }
+    // ─── CRUD Methods ───
+    /**
+     * List records with filters, sorting, and pagination.
+     * Parses server response into unified ListResult with both offset and cursor fields.
+     */
+    async getList() {
+        const query = this.buildQueryParams();
+        let data;
+        if (this.searchQuery) {
+            query.search = this.searchQuery;
+            data = await coreGet(this.core, 'search', this.namespace, this.instanceId, this.name, { query });
+        }
+        else {
+            data = await coreGet(this.core, 'list', this.namespace, this.instanceId, this.name, { query });
+        }
+        return {
+            items: (data.items ?? []),
+            total: data.total !== undefined ? data.total : null,
+            page: data.page !== undefined ? data.page : null,
+            perPage: data.perPage !== undefined ? data.perPage : null,
+            hasMore: data.hasMore !== undefined ? data.hasMore : null,
+            cursor: data.cursor !== undefined ? data.cursor : null,
+        };
+    }
+    /** Alias for getList() to match existing docs and SDK usage. */
+    async get() {
+        return this.getList();
+    }
+    /** Get a single record by ID */
+    async getOne(id) {
+        return coreGet(this.core, 'get', this.namespace, this.instanceId, this.name, { id, query: {} });
+    }
+    /**
+     * Get the first record matching the current query conditions.
+     * Returns null if no records match.
+     *
+     * @example
+     * const user = await client.db('shared').table('users')
+     *   .where('email', '==', 'june@example.com')
+     *   .getFirst();
+     */
+    async getFirst() {
+        const result = await this.limit(1).getList();
+        return result.items[0] ?? null;
+    }
+    /** Insert a new record */
+    async insert(data) {
+        return coreInsert(this.core, this.namespace, this.instanceId, this.name, data);
+    }
+    /** Update a record by ID (supports increment, deleteField) */
+    async update(id, data) {
+        const serialized = serializeFieldOps(data);
+        return coreUpdate(this.core, this.namespace, this.instanceId, this.name, id, serialized);
+    }
+    /** Delete a record by ID */
+    async delete(id) {
+        await coreDelete(this.core, this.namespace, this.instanceId, this.name, id);
+    }
+    // ─── Special Methods ───
+    /** Upsert: insert or update */
+    async upsert(data, options) {
+        const query = { upsert: 'true' };
+        if (options?.conflictTarget)
+            query.conflictTarget = options.conflictTarget;
+        return coreInsert(this.core, this.namespace, this.instanceId, this.name, data, query);
+    }
+    /** Batch upsert */
+    async upsertMany(items, options) {
+        const CHUNK_SIZE = 500;
+        const query = { upsert: 'true' };
+        if (options?.conflictTarget)
+            query.conflictTarget = options.conflictTarget;
+        // Fast path: no chunking needed
+        if (items.length <= CHUNK_SIZE) {
+            const result = await coreBatch(this.core, this.namespace, this.instanceId, this.name, { inserts: items }, query);
+            return result.inserted;
+        }
+        // Chunk into 500-item batches
+        const allInserted = [];
+        for (let i = 0; i < items.length; i += CHUNK_SIZE) {
+            const chunk = items.slice(i, i + CHUNK_SIZE);
+            const result = await coreBatch(this.core, this.namespace, this.instanceId, this.name, { inserts: chunk }, query);
+            allInserted.push(...result.inserted);
+        }
+        return allInserted;
+    }
+    /** Count records matching filters */
+    async count() {
+        const query = this.buildQueryParams();
+        const result = await coreGet(this.core, 'count', this.namespace, this.instanceId, this.name, { query });
+        return result.total;
+    }
+    /**
+     * Batch insert.
+     * Auto-chunks into 500-item batches.
+     * Each chunk is an independent transaction — partial failure possible across chunks.
+     */
+    async insertMany(items) {
+        const CHUNK_SIZE = 500;
+        // Fast path: no chunking needed
+        if (items.length <= CHUNK_SIZE) {
+            const result = await coreBatch(this.core, this.namespace, this.instanceId, this.name, { inserts: items });
+            return result.inserted;
+        }
+        // Chunk into 500-item batches
+        const allInserted = [];
+        for (let i = 0; i < items.length; i += CHUNK_SIZE) {
+            const chunk = items.slice(i, i + CHUNK_SIZE);
+            const result = await coreBatch(this.core, this.namespace, this.instanceId, this.name, { inserts: chunk });
+            allInserted.push(...result.inserted);
+        }
+        return allInserted;
+    }
+    /**
+     * Batch update matching records.
+     * Processes 500 records per call, max 100 iterations.
+     */
+    async updateMany(data) {
+        const filter = this.filters;
+        if (filter.length === 0) {
+            throw new EdgeBaseError(400, 'updateMany requires at least one where() filter');
+        }
+        const serialized = serializeFieldOps(data);
+        return this.batchByFilter('update', filter, serialized);
+    }
+    /**
+     * Batch delete matching records.
+     * Processes 500 records per call, max 100 iterations.
+     */
+    async deleteMany() {
+        const filter = this.filters;
+        if (filter.length === 0) {
+            throw new EdgeBaseError(400, 'deleteMany requires at least one where() filter');
+        }
+        return this.batchByFilter('delete', filter);
+    }
+    /** Internal: batch-by-filter calls */
+    async batchByFilter(action, filter, update) {
+        const MAX_ITERATIONS = 100;
+        let totalProcessed = 0;
+        let totalSucceeded = 0;
+        const errors = [];
+        for (let chunkIndex = 0; chunkIndex < MAX_ITERATIONS; chunkIndex++) {
+            try {
+                const body = { action, filter, limit: 500 };
+                if (this.orFilters.length > 0)
+                    body.orFilter = this.orFilters;
+                if (action === 'update' && update) {
+                    body.update = update;
+                }
+                const result = await coreBatchByFilter(this.core, this.namespace, this.instanceId, this.name, body);
+                totalProcessed += result.processed;
+                totalSucceeded += result.succeeded;
+                if (result.processed === 0)
+                    break; // No more matching records
+                // For 'update', don't loop — updated records still match the filter,
+                // so re-querying would process the same rows again (infinite loop).
+                // Only 'delete' benefits from looping since deleted rows disappear.
+                if (action === 'update')
+                    break;
+            }
+            catch (error) {
+                errors.push({ chunkIndex, chunkSize: 500, error: error });
+                break; // Stop on error (partial failure)
+            }
+        }
+        return { totalProcessed, totalSucceeded, errors };
+    }
+    // ─── Database Live ───
+    /**
+     * Subscribe to table changes via database-live.
+     * By default, client-side filtering is applied for where() conditions.
+     * With `{ serverFilter: true }`, filters are evaluated server-side for bandwidth savings.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * // Client-side filtering (default)
+     * const unsub = client.db('shared').table('posts')
+     *   .where('status', '==', 'published')
+     *   .onSnapshot((snapshot) => {
+     *     console.log('Updated posts:', snapshot.items);
+     *   });
+     */
+    onSnapshot(callback, options) {
+        if (!this.databaseLiveClient) {
+            throw new EdgeBaseError(500, 'IDatabaseLiveSubscriber not available');
+        }
+        const channel = buildDatabaseLiveChannel(this.namespace, this.instanceId, this.name);
+        const currentFilters = [...this.filters];
+        const currentOrFilters = [...this.orFilters];
+        const useServerFilter = options?.serverFilter === true && (currentFilters.length > 0 || currentOrFilters.length > 0);
+        // Accumulate state locally
+        const items = new Map();
+        const pendingChanges = { added: [], modified: [], removed: [] };
+        let flushTimer = null;
+        const flush = () => {
+            if (pendingChanges.added.length || pendingChanges.modified.length || pendingChanges.removed.length) {
+                callback({
+                    items: Array.from(items.values()),
+                    changes: { ...pendingChanges },
+                });
+                pendingChanges.added = [];
+                pendingChanges.modified = [];
+                pendingChanges.removed = [];
+            }
+            flushTimer = null;
+        };
+        const scheduleFlush = () => {
+            if (!flushTimer) {
+                flushTimer = setTimeout(flush, 0);
+            }
+        };
+        return this.databaseLiveClient.onSnapshot(channel, (change) => {
+            const data = change.data;
+            const docId = change.docId;
+            const hasFilterConstraints = currentFilters.length > 0 || currentOrFilters.length > 0;
+            const hadItem = items.has(docId);
+            // Client-side filtering — skip if server-side filter is active
+            if (!useServerFilter && hasFilterConstraints) {
+                if (change.changeType === 'removed') {
+                    if (!hadItem)
+                        return;
+                }
+                else if (!data || !matchesSnapshotFilters(data, currentFilters, currentOrFilters, this.filterMatchFn)) {
+                    if (hadItem) {
+                        items.delete(docId);
+                        pendingChanges.removed.push((data ?? { id: docId }));
+                        scheduleFlush();
+                    }
+                    return;
+                }
+            }
+            switch (change.changeType) {
+                case 'added':
+                    if (data)
+                        items.set(docId, data);
+                    pendingChanges[hadItem ? 'modified' : 'added'].push(data);
+                    break;
+                case 'modified':
+                    if (data)
+                        items.set(docId, data);
+                    pendingChanges[hadItem ? 'modified' : 'added'].push(data);
+                    break;
+                case 'removed':
+                    items.delete(docId);
+                    pendingChanges.removed.push((data ?? { id: docId }));
+                    break;
+            }
+            scheduleFlush();
+        }, undefined, // client-side filters (not used for server-side)
+        useServerFilter ? currentFilters : undefined, // server-side filters
+        useServerFilter ? currentOrFilters : undefined);
+    }
+    /**
+     * Execute raw SQL on this table's DO.
+     * Tagged template — interpolated values are automatically extracted as bind params,
+     * preventing SQL injection.
+     *
+     * NOTE: Admin-only (/api/sql). Uses raw HttpClient since this endpoint is
+     * in the admin core, not the client core. Requires Service Key auth.
+     *
+     * @example
+     * // In App Functions or server-side code
+     * const results = await context.admin.db('shared').table('posts').sql`
+     *   SELECT p.*, COUNT(c.id) as commentCount
+     *   FROM posts p LEFT JOIN comments c ON c.postId = p.id
+     *   WHERE p.status = ${'published'}
+     *   GROUP BY p.id
+     * `;
+     */
+    async sql(strings, ...values) {
+        if (!this._httpClient) {
+            throw new EdgeBaseError(500, 'sql() requires HttpClient (admin-only method). Use context.admin.db(...).table(...).sql`...`');
+        }
+        // Build parameterized query from tagged template — each ${} becomes ?
+        let query = '';
+        const params = [];
+        for (let i = 0; i < strings.length; i++) {
+            query += strings[i];
+            if (i < values.length) {
+                query += '?';
+                params.push(values[i]);
+            }
+        }
+        // §11: body uses { namespace, id, sql, params }
+        // /api/sql is admin-only, tagged 'admin', lives in admin core — not client core.
+        return this._httpClient.post(ApiPaths.EXECUTE_SQL, {
+            namespace: this.namespace,
+            id: this.instanceId,
+            sql: query.trim(),
+            params,
+        });
+    }
+}
+// ─── DbRef ───
+/**
+ * DB block reference. Returned by `client.db(namespace, id?)`.
+ * Provides `.table(name)` to get a TableRef for a specific table.
+ *
+ * @example
+ * // Static shared DB
+ * const postsRef = client.db('shared').table('posts');
+ *
+ * // Dynamic workspace DB
+ * const docsRef = client.db('workspace', 'ws-456').table('documents');
+ */
+export class DbRef {
+    core;
+    namespace;
+    instanceId;
+    databaseLiveClient;
+    filterMatchFn;
+    _httpClient;
+    constructor(core, 
+    /** DB namespace: 'shared' | 'workspace' | 'user' | ... */
+    namespace, 
+    /** DB instance ID for dynamic DOs (e.g. 'ws-456'). Omit for static DBs. */
+    instanceId, databaseLiveClient, filterMatchFn, 
+    /**
+     * Raw HttpClient — only passed through to TableRef for sql().
+     * TODO: remove once admin core is wired.
+     */
+    _httpClient) {
+        this.core = core;
+        this.namespace = namespace;
+        this.instanceId = instanceId;
+        this.databaseLiveClient = databaseLiveClient;
+        this.filterMatchFn = filterMatchFn;
+        this._httpClient = _httpClient;
+    }
+    /**
+     * Select a table within this DB block.
+     * Returns a TableRef configured with the correct namespace/instanceId.
+     *
+     * @param name — Table name (as defined in config.databases[namespace].tables)
+     */
+    table(name) {
+        return new TableRef(this.core, name, this.databaseLiveClient, this.filterMatchFn, this.namespace, this.instanceId, this._httpClient);
+    }
+}
+// ─── OrBuilder ───
+/**
+ * Builder for OR conditions.
+ * Used with .or() method on TableRef.
+ *
+ * @example
+ * client.db('shared').table('posts')
+ *   .or(q => q.where('status', '==', 'draft').where('authorId', '==', 'user-123'))
+ *   .getList()
+ */
+export class OrBuilder {
+    filters = [];
+    where(field, operator, value) {
+        this.filters.push([field, operator, value]);
+        return this;
+    }
+    getFilters() {
+        return [...this.filters];
+    }
+}
+//# sourceMappingURL=table.js.map