@moltendb-web/query 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,360 @@
+/** A plain JSON-serialisable value. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A document stored in MoltenDB — any object with string keys. */
+export type Document = {
+    [key: string]: JsonValue;
+};
+/** A map of document key → document body used in set/update payloads. */
+export type DataMap = {
+    [key: string]: Document;
+};
+/** Comparison operators supported in a WHERE clause. */
+export interface WhereOperators {
+    $eq?: JsonValue;
+    $ne?: JsonValue;
+    $gt?: number;
+    $gte?: number;
+    $lt?: number;
+    $lte?: number;
+    $in?: JsonValue[];
+    $nin?: JsonValue[];
+    $contains?: JsonValue;
+}
+/**
+ * A WHERE clause: each key is a field path (dot-notation supported),
+ * and the value is either a plain value (implicit equality) or an operator object.
+ */
+export type WhereClause = {
+    [field: string]: JsonValue | WhereOperators;
+};
+/** A single sort specification. */
+export interface SortSpec {
+    field: string;
+    order?: 'asc' | 'desc';
+}
+/** A single join specification. */
+export interface JoinSpec {
+    /** The alias under which the joined document is embedded. */
+    alias: string;
+    /** The collection to join from. */
+    from: string;
+    /** The foreign-key field path on the main document. */
+    on: string;
+    /** Optional field projection on the joined document. */
+    fields?: string[];
+}
+/**
+ * Inline reference embedding at insert time.
+ * Format: { alias: "collection.key" }
+ * Example: { ram: "memory.mem4", screen: "display.dsp3" }
+ */
+export type ExtendsMap = {
+    [alias: string]: string;
+};
+/**
+ * The transport layer used by MoltenDBClient to send messages.
+ * Implement this interface to connect the query builder to any backend:
+ *   - A Web Worker (WASM in-browser)
+ *   - A fetch-based HTTP client
+ *   - A WebSocket connection
+ *   - A mock for testing
+ */
+export interface MoltenTransport {
+    send(action: 'get' | 'set' | 'update' | 'delete', payload: Document): Promise<JsonValue>;
+}
+/**
+ * Default transport that communicates with a MoltenDB Web Worker.
+ *
+ * The worker must follow the moltendb-worker.js message protocol:
+ *   postMessage({ id, action, ...payload })
+ *   onmessage → { id, result } | { id, error }
+ */
+export declare class WorkerTransport implements MoltenTransport {
+    private worker;
+    private messageId;
+    private pending;
+    constructor(worker: Worker, startId?: number);
+    send(action: 'get' | 'set' | 'update' | 'delete', payload: Document): Promise<JsonValue>;
+}
+/**
+ * Builder for GET (read/query) operations.
+ *
+ * Allowed fields: collection, keys, where, fields, excludedFields,
+ *                 joins, sort, count, offset
+ *
+ * @example
+ * const rows = await db.collection('laptops')
+ *   .get()
+ *   .where({ brand: 'Apple' })
+ *   .fields(['brand', 'model', 'price'])
+ *   .sort([{ field: 'price', order: 'asc' }])
+ *   .count(5)
+ *   .exec();
+ */
+export declare class GetQuery {
+    private payload;
+    private transport;
+    /** @internal */
+    constructor(transport: MoltenTransport, collection: string);
+    /**
+     * Fetch a single document by key, or a batch of documents by key array.
+     *
+     * @param keys - A single key string or an array of key strings.
+     *
+     * @example
+     * // Single key
+     * .keys('lp2')
+     * // Batch
+     * .keys(['lp1', 'lp3', 'lp5'])
+     */
+    keys(keys: string | string[]): this;
+    /**
+     * Filter documents using a WHERE clause.
+     * Multiple conditions are combined with implicit AND.
+     *
+     * Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains
+     * Dot-notation is supported for nested fields.
+     *
+     * @example
+     * .where({ brand: 'Apple' })
+     * .where({ price: { $gt: 1000, $lt: 3000 } })
+     * .where({ 'specs.cpu.brand': 'Intel', in_stock: true })
+     */
+    where(clause: WhereClause): this;
+    /**
+     * Project the response to only the specified fields (dot-notation supported).
+     * Cannot be combined with {@link excludedFields}.
+     *
+     * @example
+     * .fields(['brand', 'model', 'specs.cpu.ghz'])
+     */
+    fields(fields: string[]): this;
+    /**
+     * Return all fields except the specified ones.
+     * Cannot be combined with {@link fields}.
+     *
+     * @example
+     * .excludedFields(['price', 'memory_id', 'display_id'])
+     */
+    excludedFields(fields: string[]): this;
+    /**
+     * Join related documents from other collections.
+     * Each join embeds the related document under the given alias.
+     *
+     * @example
+     * .joins([
+     *   { alias: 'ram',    from: 'memory',  on: 'memory_id',  fields: ['capacity_gb', 'type'] },
+     *   { alias: 'screen', from: 'display', on: 'display_id', fields: ['refresh_hz', 'panel'] },
+     * ])
+     */
+    joins(specs: JoinSpec[]): this;
+    /**
+     * Sort the results.
+     * Multiple specs are applied in priority order (first = primary sort key).
+     *
+     * @example
+     * .sort([{ field: 'price', order: 'asc' }])
+     * .sort([{ field: 'brand', order: 'asc' }, { field: 'price', order: 'desc' }])
+     */
+    sort(specs: SortSpec[]): this;
+    /**
+     * Limit the number of results returned (applied after filtering and sorting).
+     *
+     * @example
+     * .count(10)
+     */
+    count(n: number): this;
+    /**
+     * Skip the first N results (for pagination, applied after sorting).
+     *
+     * @example
+     * .offset(20).count(10)  // page 3 of 10
+     */
+    offset(n: number): this;
+    /**
+     * Build and return the raw JSON payload without sending it.
+     * Useful for debugging or passing to a custom transport.
+     */
+    build(): Document;
+    /**
+     * Execute the query and return the result.
+     * Returns a single document for single-key lookups, or an array for all others.
+     */
+    exec(): Promise<JsonValue>;
+}
+/**
+ * Builder for SET (insert / upsert) operations.
+ *
+ * Allowed fields: collection, data, extends
+ *
+ * @example
+ * await db.collection('laptops')
+ *   .set({
+ *     lp1: { brand: 'Lenovo', model: 'ThinkPad X1', price: 1499 },
+ *     lp2: { brand: 'Apple',  model: 'MacBook Pro', price: 3499 },
+ *   })
+ *   .exec();
+ */
+export declare class SetQuery {
+    private payload;
+    private transport;
+    /** @internal */
+    constructor(transport: MoltenTransport, collection: string, data: DataMap | Document[]);
+    /**
+     * Embed data from other collections into each document at insert time.
+     * The referenced document is fetched once and stored as a snapshot.
+     *
+     * Format: `{ alias: "collection.key" }`
+     *
+     * @example
+     * .extends({ ram: 'memory.mem4', screen: 'display.dsp3' })
+     */
+    extends(map: ExtendsMap): this;
+    /** Build and return the raw JSON payload without sending it. */
+    build(): Document;
+    /** Execute the insert/upsert and return `{ count, status }`. */
+    exec(): Promise<JsonValue>;
+}
+/**
+ * Builder for UPDATE (partial patch / merge) operations.
+ *
+ * Allowed fields: collection, data
+ *
+ * Only the fields present in each patch object are updated —
+ * all other fields on the existing document are left unchanged.
+ *
+ * @example
+ * await db.collection('laptops')
+ *   .update({ lp4: { price: 1749, in_stock: true } })
+ *   .exec();
+ */
+export declare class UpdateQuery {
+    private payload;
+    private transport;
+    /** @internal */
+    constructor(transport: MoltenTransport, collection: string, data: DataMap);
+    /** Build and return the raw JSON payload without sending it. */
+    build(): Document;
+    /** Execute the patch and return `{ count, status }`. */
+    exec(): Promise<JsonValue>;
+}
+/**
+ * Builder for DELETE operations.
+ *
+ * Allowed fields: collection, keys, drop
+ *
+ * @example
+ * // Delete a single document
+ * await db.collection('laptops').delete().keys('lp6').exec();
+ *
+ * // Delete multiple documents
+ * await db.collection('laptops').delete().keys(['lp4', 'lp5']).exec();
+ *
+ * // Drop the entire collection
+ * await db.collection('laptops').delete().drop().exec();
+ */
+export declare class DeleteQuery {
+    private payload;
+    private transport;
+    /** @internal */
+    constructor(transport: MoltenTransport, collection: string);
+    /**
+     * Delete a single document by key, or multiple documents by key array.
+     *
+     * @example
+     * .keys('lp6')
+     * .keys(['lp4', 'lp5'])
+     */
+    keys(keys: string | string[]): this;
+    /**
+     * Drop the entire collection (deletes all documents).
+     * Cannot be combined with {@link keys}.
+     *
+     * @example
+     * .drop()
+     */
+    drop(): this;
+    /** Build and return the raw JSON payload without sending it. */
+    build(): Document;
+    /** Execute the delete and return `{ count, status }`. */
+    exec(): Promise<JsonValue>;
+}
+/**
+ * A handle to a specific collection.
+ * Returned by `MoltenDBClient.collection(name)`.
+ * Use it to start any of the four operation builders.
+ */
+export declare class CollectionHandle {
+    private transport;
+    private collectionName;
+    /** @internal */
+    constructor(transport: MoltenTransport, collectionName: string);
+    /**
+     * Start a GET (read/query) builder for this collection.
+     *
+     * @example
+     * db.collection('laptops').get().where({ brand: 'Apple' }).exec()
+     */
+    get(): GetQuery;
+    /**
+     * Start a SET (insert/upsert) builder for this collection.
+     *
+     * @param data - A map of `{ key: document }` pairs, or an array of documents
+     *               (keys are auto-generated as UUIDv7 when using array format).
+     *
+     * @example
+     * db.collection('laptops').set({ lp1: { brand: 'Lenovo', price: 1499 } }).exec()
+     */
+    set(data: DataMap | Document[]): SetQuery;
+    /**
+     * Start an UPDATE (partial patch) builder for this collection.
+     *
+     * @param data - A map of `{ key: patch }` pairs. Only the provided fields are updated.
+     *
+     * @example
+     * db.collection('laptops').update({ lp4: { price: 1749 } }).exec()
+     */
+    update(data: DataMap): UpdateQuery;
+    /**
+     * Start a DELETE builder for this collection.
+     * Chain `.keys(...)` or `.drop()` to specify what to delete.
+     *
+     * @example
+     * db.collection('laptops').delete().keys('lp6').exec()
+     */
+    delete(): DeleteQuery;
+}
+/**
+ * The main entry point for the MoltenDB query builder.
+ *
+ * Accepts any {@link MoltenTransport} implementation — use {@link WorkerTransport}
+ * to connect to a MoltenDB WASM Web Worker, or provide your own transport
+ * for HTTP, WebSocket, or testing.
+ *
+ * @example
+ * // Browser + WASM Web Worker
+ * const worker = new Worker('./moltendb-worker.js', { type: 'module' });
+ * const transport = new WorkerTransport(worker);
+ * const db = new MoltenDBClient(transport);
+ *
+ * const results = await db.collection('laptops')
+ *   .get()
+ *   .where({ in_stock: true })
+ *   .sort([{ field: 'price', order: 'asc' }])
+ *   .count(5)
+ *   .exec();
+ */
+export declare class MoltenDBQueryBuilder {
+    private transport;
+    constructor(transport: MoltenTransport);
+    /**
+     * Select a collection to operate on.
+     * Returns a {@link CollectionHandle} from which you can start any query builder.
+     *
+     * @param name - The collection name (e.g. `'laptops'`).
+     */
+    collection(name: string): CollectionHandle;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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