@moltendb-web/query 0.1.0

package/README.md

@@ -0,0 +1,209 @@
+# @moltendb-web/query
+
+Type-safe, chainable query builder for [MoltenDB](https://github.com/maximilian27/MoltenDB).
+
+Works in vanilla JavaScript and TypeScript. Compiles as an npm module (CJS + ESM + `.d.ts`).
+
+---
+
+## Installation
+
+```bash
+npm install @moltendb-web/query
+```
+
+---
+
+## Quick start
+
+```ts
+import { MoltenDBClient, WorkerTransport } from '@moltendb-web/query';
+
+// Connect to a MoltenDB WASM Web Worker
+const worker = new Worker('./moltendb-worker.js', { type: 'module' });
+const db = new MoltenDBClient(new WorkerTransport(worker));
+
+// GET — query with WHERE, field projection, sort and pagination
+const results = await db.collection('laptops')
+  .get()
+  .where({ brand: 'Apple' })
+  .fields(['brand', 'model', 'price'])
+  .sort([{ field: 'price', order: 'asc' }])
+  .count(5)
+  .exec();
+
+// SET — insert / upsert
+await db.collection('laptops')
+  .set({
+    lp1: { brand: 'Lenovo', model: 'ThinkPad X1', price: 1499, in_stock: true },
+    lp2: { brand: 'Apple',  model: 'MacBook Pro',  price: 3499, in_stock: true },
+  })
+  .exec();
+
+// UPDATE — partial patch (only listed fields are changed)
+await db.collection('laptops')
+  .update({ lp4: { price: 1749, in_stock: true } })
+  .exec();
+
+// DELETE — single key
+await db.collection('laptops').delete().keys('lp6').exec();
+
+// DELETE — batch
+await db.collection('laptops').delete().keys(['lp4', 'lp5']).exec();
+
+// DELETE — drop entire collection
+await db.collection('laptops').delete().drop().exec();
+```
+
+---
+
+## Operations & allowed fields
+
+Each operation only exposes the methods that are valid for it — invalid
+combinations are caught at compile time by TypeScript.
+
+### `get()` — read / query
+
+| Method | Description |
+|---|---|
+| `.keys(key \| key[])` | Fetch one or more documents by key |
+| `.where(clause)` | Filter with operators: `$eq $ne $gt $gte $lt $lte $in $nin $contains` |
+| `.fields(string[])` | Return only these fields (dot-notation supported) |
+| `.excludedFields(string[])` | Return everything except these fields |
+| `.joins(JoinSpec[])` | Embed related documents from other collections |
+| `.sort(SortSpec[])` | Sort results (multi-field, asc/desc) |
+| `.count(n)` | Limit results to N documents |
+| `.offset(n)` | Skip first N results (pagination) |
+| `.build()` | Return the raw JSON payload without sending |
+| `.exec()` | Send the query and return the result |
+
+### `set(data)` — insert / upsert
+
+| Method | Description |
+|---|---|
+| `.extends(map)` | Embed snapshots from other collections at insert time |
+| `.build()` | Return the raw JSON payload without sending |
+| `.exec()` | Send and return `{ count, status }` |
+
+`data` can be a `{ key: document }` map or a `Document[]` array (UUIDv7 keys are auto-assigned for arrays).
+
+### `update(data)` — partial patch
+
+| Method | Description |
+|---|---|
+| `.build()` | Return the raw JSON payload without sending |
+| `.exec()` | Send and return `{ count, status }` |
+
+Only the fields present in each patch object are updated — all other fields are left unchanged.
+
+### `delete()` — delete documents or drop collection
+
+| Method | Description |
+|---|---|
+| `.keys(key \| key[])` | Delete one or more documents by key |
+| `.drop()` | Drop the entire collection |
+| `.build()` | Return the raw JSON payload without sending |
+| `.exec()` | Send and return `{ count, status }` |
+
+---
+
+## WHERE operators
+
+```ts
+// Exact equality (implicit)
+.where({ brand: 'Apple' })
+
+// Comparison
+.where({ price: { $gt: 1000, $lt: 3000 } })
+.where({ 'specs.cpu.cores': { $gte: 12 } })
+
+// Not equal
+.where({ 'specs.cpu.brand': { $ne: 'Intel' } })
+
+// In / not-in list
+.where({ brand: { $in: ['Apple', 'Dell'] } })
+.where({ brand: { $nin: ['Framework'] } })
+
+// Contains (string substring or array element)
+.where({ model: { $contains: 'Pro' } })
+.where({ tags:  { $contains: 'gaming' } })
+
+// Multiple conditions (implicit AND)
+.where({ in_stock: true, 'specs.cpu.brand': 'Intel' })
+```
+
+---
+
+## Joins
+
+```ts
+const results = await db.collection('laptops')
+  .get()
+  .fields(['brand', 'model', 'price'])
+  .joins([
+    { alias: 'ram',    from: 'memory',  on: 'memory_id',  fields: ['capacity_gb', 'type'] },
+    { alias: 'screen', from: 'display', on: 'display_id', fields: ['refresh_hz', 'panel'] },
+  ])
+  .exec();
+// Each result: { brand, model, price, ram: { capacity_gb, type }, screen: { refresh_hz, panel } }
+```
+
+---
+
+## Extends (snapshot embedding at insert time)
+
+```ts
+await db.collection('laptops')
+  .set({
+    lp7: {
+      brand: 'MSI', model: 'Titan GT77', price: 3299,
+      specs: { cpu: { brand: 'Intel', cores: 16, ghz: 5.0 } },
+    },
+  })
+  .extends({ ram: 'memory.mem4', screen: 'display.dsp3' })
+  .exec();
+// lp7 is stored with the full mem4 and dsp3 documents embedded inline.
+```
+
+---
+
+## Custom transport
+
+Implement `MoltenTransport` to connect to any backend:
+
+```ts
+import { MoltenTransport, MoltenDBClient, Document, JsonValue } from '@moltendb-web/query';
+
+class FetchTransport implements MoltenTransport {
+  constructor(private baseUrl: string, private token: string) {}
+
+  async send(action: 'get' | 'set' | 'update' | 'delete', payload: Document): Promise<JsonValue> {
+    const res = await fetch(`${this.baseUrl}/${action}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.token}`,
+      },
+      body: JSON.stringify(payload),
+    });
+    return res.json();
+  }
+}
+
+const db = new MoltenDBClient(new FetchTransport('https://localhost:1538', myToken));
+```
+
+---
+
+## Build
+
+```bash
+npm run build      # emit dist/index.js (CJS), dist/index.esm.js (ESM), dist/index.d.ts
+npm run typecheck  # type-check without emitting
+```
+
+---
+
+## License
+
+MIT OR Apache-2.0

package/dist/esm/index.js

@@ -0,0 +1,443 @@
+// ─── MoltenDB Query Builder ───────────────────────────────────────────────────
+// Chainable, type-safe query builder for MoltenDB.
+//
+// Each operation has its own builder class that only exposes the methods
+// that are valid for that operation — matching the server's allowed-property
+// lists exactly:
+//
+//   GET_ALLOWED:    collection, keys, where, fields, excludedFields,
+//                   joins, sort, count, offset
+//   SET_ALLOWED:    collection, data, extends
+//   UPDATE_ALLOWED: collection, data
+//   DELETE_ALLOWED: collection, keys, drop
+//
+// Usage (vanilla JS or TypeScript):
+//
+//   const db = new MoltenDBClient(worker);
+//
+//   // GET — chainable query
+//   const results = await db.collection('laptops')
+//     .get()
+//     .where({ brand: 'Apple' })
+//     .fields(['brand', 'model', 'price'])
+//     .sort([{ field: 'price', order: 'asc' }])
+//     .count(10)
+//     .exec();
+//
+//   // SET — insert/upsert
+//   await db.collection('laptops')
+//     .set({ lp1: { brand: 'Lenovo', price: 1499 } })
+//     .exec();
+//
+//   // UPDATE — partial patch
+//   await db.collection('laptops')
+//     .update({ lp4: { price: 1749, in_stock: true } })
+//     .exec();
+//
+//   // DELETE — single key, batch, or drop
+//   await db.collection('laptops').delete().keys('lp6').exec();
+//   await db.collection('laptops').delete().keys(['lp4', 'lp5']).exec();
+//   await db.collection('laptops').delete().drop().exec();
+// ─────────────────────────────────────────────────────────────────────────────
+// ─── WorkerTransport ──────────────────────────────────────────────────────────
+/**
+ * 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 class WorkerTransport {
+    constructor(worker, startId = 0) {
+        this.pending = new Map();
+        this.messageId = startId;
+        this.worker = worker;
+        this.worker.addEventListener('message', (event) => {
+            const { id, result, error } = event.data;
+            const p = this.pending.get(id);
+            if (!p)
+                return;
+            this.pending.delete(id);
+            if (error)
+                p.reject(new Error(error));
+            else
+                p.resolve(result ?? null);
+        });
+    }
+    send(action, payload) {
+        return new Promise((resolve, reject) => {
+            const id = this.messageId++;
+            this.pending.set(id, { resolve, reject });
+            this.worker.postMessage({ id, action, ...payload });
+        });
+    }
+}
+// ─── GetQuery ─────────────────────────────────────────────────────────────────
+/**
+ * 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 class GetQuery {
+    /** @internal */
+    constructor(transport, collection) {
+        this.transport = transport;
+        this.payload = { collection };
+    }
+    /**
+     * 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) {
+        this.payload['keys'] = keys;
+        return 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) {
+        this.payload['where'] = clause;
+        return 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) {
+        this.payload['fields'] = fields;
+        return this;
+    }
+    /**
+     * Return all fields except the specified ones.
+     * Cannot be combined with {@link fields}.
+     *
+     * @example
+     * .excludedFields(['price', 'memory_id', 'display_id'])
+     */
+    excludedFields(fields) {
+        this.payload['excludedFields'] = fields;
+        return 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) {
+        this.payload['joins'] = specs.map(({ alias, from, on, fields }) => ({
+            [alias]: fields ? { from, on, fields } : { from, on },
+        }));
+        return 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) {
+        this.payload['sort'] = specs;
+        return this;
+    }
+    /**
+     * Limit the number of results returned (applied after filtering and sorting).
+     *
+     * @example
+     * .count(10)
+     */
+    count(n) {
+        this.payload['count'] = n;
+        return this;
+    }
+    /**
+     * Skip the first N results (for pagination, applied after sorting).
+     *
+     * @example
+     * .offset(20).count(10)  // page 3 of 10
+     */
+    offset(n) {
+        this.payload['offset'] = n;
+        return this;
+    }
+    /**
+     * Build and return the raw JSON payload without sending it.
+     * Useful for debugging or passing to a custom transport.
+     */
+    build() {
+        return { ...this.payload };
+    }
+    /**
+     * Execute the query and return the result.
+     * Returns a single document for single-key lookups, or an array for all others.
+     */
+    exec() {
+        return this.transport.send('get', this.payload);
+    }
+}
+// ─── SetQuery ─────────────────────────────────────────────────────────────────
+/**
+ * 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 class SetQuery {
+    /** @internal */
+    constructor(transport, collection, data) {
+        this.transport = transport;
+        this.payload = { collection, data: data };
+    }
+    /**
+     * 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) {
+        // The extends map is applied to every document in data.
+        // We store it at the top level; the server resolves it per-document.
+        const data = this.payload['data'];
+        if (Array.isArray(data)) {
+            // Array format — inject extends into each item
+            this.payload['data'] = data.map((doc) => ({
+                ...doc,
+                extends: map,
+            }));
+        }
+        else if (data && typeof data === 'object') {
+            // Object format — inject extends into each document value
+            const updated = {};
+            for (const [key, doc] of Object.entries(data)) {
+                updated[key] = { ...doc, extends: map };
+            }
+            this.payload['data'] = updated;
+        }
+        return this;
+    }
+    /** Build and return the raw JSON payload without sending it. */
+    build() {
+        return { ...this.payload };
+    }
+    /** Execute the insert/upsert and return `{ count, status }`. */
+    exec() {
+        return this.transport.send('set', this.payload);
+    }
+}
+// ─── UpdateQuery ──────────────────────────────────────────────────────────────
+/**
+ * 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 class UpdateQuery {
+    /** @internal */
+    constructor(transport, collection, data) {
+        this.transport = transport;
+        this.payload = { collection, data: data };
+    }
+    /** Build and return the raw JSON payload without sending it. */
+    build() {
+        return { ...this.payload };
+    }
+    /** Execute the patch and return `{ count, status }`. */
+    exec() {
+        return this.transport.send('update', this.payload);
+    }
+}
+// ─── DeleteQuery ──────────────────────────────────────────────────────────────
+/**
+ * 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 class DeleteQuery {
+    /** @internal */
+    constructor(transport, collection) {
+        this.transport = transport;
+        this.payload = { collection };
+    }
+    /**
+     * Delete a single document by key, or multiple documents by key array.
+     *
+     * @example
+     * .keys('lp6')
+     * .keys(['lp4', 'lp5'])
+     */
+    keys(keys) {
+        this.payload['keys'] = keys;
+        return this;
+    }
+    /**
+     * Drop the entire collection (deletes all documents).
+     * Cannot be combined with {@link keys}.
+     *
+     * @example
+     * .drop()
+     */
+    drop() {
+        this.payload['drop'] = true;
+        return this;
+    }
+    /** Build and return the raw JSON payload without sending it. */
+    build() {
+        return { ...this.payload };
+    }
+    /** Execute the delete and return `{ count, status }`. */
+    exec() {
+        return this.transport.send('delete', this.payload);
+    }
+}
+// ─── CollectionHandle ─────────────────────────────────────────────────────────
+/**
+ * A handle to a specific collection.
+ * Returned by `MoltenDBClient.collection(name)`.
+ * Use it to start any of the four operation builders.
+ */
+export class CollectionHandle {
+    /** @internal */
+    constructor(transport, collectionName) {
+        this.transport = transport;
+        this.collectionName = collectionName;
+    }
+    /**
+     * Start a GET (read/query) builder for this collection.
+     *
+     * @example
+     * db.collection('laptops').get().where({ brand: 'Apple' }).exec()
+     */
+    get() {
+        return new GetQuery(this.transport, this.collectionName);
+    }
+    /**
+     * 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) {
+        return new SetQuery(this.transport, this.collectionName, data);
+    }
+    /**
+     * 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) {
+        return new UpdateQuery(this.transport, this.collectionName, data);
+    }
+    /**
+     * 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() {
+        return new DeleteQuery(this.transport, this.collectionName);
+    }
+}
+// ─── MoltenDBClient ───────────────────────────────────────────────────────────
+/**
+ * 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 class MoltenDBClient {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * 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) {
+        return new CollectionHandle(this.transport, name);
+    }
+}