marcidb-client 0.12.0 → 0.14.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "marcidb-client",
   "type": "module",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "license": "MIT",
   "author": {
     "name": "den59k"

package/runtime/index.d.ts

@@ -1,3 +1,391 @@
+type ServiceKeys = "$where" | "$order" | "$limit" | "$skip" | "$cursor";
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+	[key: string]: JsonValue;
+};
+type AggregateKeys = {
+	$count: true;
+} | {
+	$sum: string;
+} | {
+	$avg: string;
+} | {
+	$min: string;
+} | {
+	$max: string;
+};
+type GetResult<
+	TModel,
+	TSelect
+> = TModel extends any ? { -readonly [K in keyof Omit<TSelect, ServiceKeys> as TSelect[K] extends false | undefined ? never : K extends keyof TModel ? K : never] : K extends keyof TModel ? TSelect[K] extends true ? TModel[K] : TSelect[K] extends Record<string, any> ? TModel[K] extends readonly object[] ? TSelect[K] extends AggregateKeys ? AggregateResult<NonNullable<TModel[K][number]>, TSelect[K]> : GetResult<NonNullable<TModel[K][number]>, TSelect[K]>[] : GetResult<NonNullable<TModel[K]>, TSelect[K]> | Extract<TModel[K], null> : TModel[K] : never } : never;
+type RefUpdate<I> = {
+	"$connect"?: I;
+};
+type RefUpdateStruct<
+	I,
+	U
+> = {
+	"$update"?: U;
+	"$ensure"?: I;
+	"$set"?: I;
+};
+/** Relation to independent rows — link operations only, the rows themselves are never created
+* or deleted. `$set` replaces link membership with exactly the given set (missing links are
+* disconnected, new ones connected); `$connect` links (idempotent); `$remove` unlinks. */
+type RefListUpdate<I> = {
+	"$set"?: I[];
+	"$connect"?: I | I[];
+	"$remove"?: I | I[];
+};
+/** `@list` relation: an ordered inline id array — a sequence, so the same id may appear several
+* times. `$set` replaces the whole array (also the reorder operation); `$connect` appends at the
+* end (an already-present id gains another occurrence); `$connectUnique` appends only ids not
+* already present; `$remove` removes every occurrence. */
+type RefListUpdateOrdered<I> = {
+	"$set"?: I[];
+	"$connect"?: I | I[];
+	"$connectUnique"?: I | I[];
+	"$remove"?: I | I[];
+};
+/** Owned (struct) list: the children live and die with the parent. `$push` creates children,
+* `$update` edits single children in place (each item is the child's id fields — the shape
+* query results return — plus the changes under `data`), `$remove` deletes children by id,
+* `$set` replaces all children (deletes the current ones, creates the new). */
+type RefListUpdateStruct<
+	I,
+	U,
+	Id
+> = {
+	"$push"?: I | I[];
+	"$update"?: (Id & {
+		data: U;
+	}) | (Id & {
+		data: U;
+	})[];
+	"$remove"?: Id | Id[];
+	"$set"?: I[];
+};
+/** Variable-length primitive array — a sequence, so the same value may appear several times.
+* `$push` appends at the end (duplicates kept); `$pushUnique` appends only values not already
+* present; `$remove` removes every occurrence; `$set` replaces the whole array (also the
+* positional-edit path — send the full new array). One operator per update. */
+type PrimitiveListUpdate<T> = {
+	"$set"?: T[];
+	"$push"?: T | T[];
+	"$pushUnique"?: T | T[];
+	"$remove"?: T | T[];
+};
+type Never<T> = { [K in keyof T]? : never };
+type FieldOps = {
+	"$eq": unknown;
+	"$ne": unknown;
+	"$not": unknown;
+	"$in": unknown;
+	"$notIn": unknown;
+	"$gt": unknown;
+	"$gte": unknown;
+	"$lt": unknown;
+	"$lte": unknown;
+	"$startsWith": unknown;
+	"$includes": unknown;
+	"$every": unknown;
+	"$some": unknown;
+	"$none": unknown;
+	"$near": unknown;
+	"$search": unknown;
+};
+type Only<
+	K extends keyof FieldOps,
+	V
+> = { [P in K] : V } & Never<Omit<FieldOps, K>>;
+type WhereValue<T> = (T & Never<{
+	"$and": unknown;
+	"$or": unknown;
+	"$not": unknown;
+}>) | ({
+	"$and": WhereValue<T>[];
+} & Never<T> & Never<{
+	"$or": unknown;
+	"$not": unknown;
+}>) | ({
+	"$or": WhereValue<T>[];
+} & Never<T> & Never<{
+	"$and": unknown;
+	"$not": unknown;
+}>) | ({
+	"$not": WhereValue<T>;
+} & Never<T> & Never<{
+	"$and": unknown;
+	"$or": unknown;
+}>);
+type ValueOps<T> = {
+	"$eq"?: T;
+	"$ne"?: T;
+	"$not"?: T;
+	"$in"?: T[];
+	"$notIn"?: T[];
+};
+type NumOps<T> = {
+	"$gt"?: T;
+	"$gte"?: T;
+	"$lt"?: T;
+	"$lte"?: T;
+};
+type StrOps = {
+	"$includes"?: string;
+	"$startsWith"?: string;
+};
+type CompareValue<T> = T | (ValueOps<T> & Never<Omit<FieldOps, keyof ValueOps<T>>>);
+type CompareNumValue<T> = ValueOps<T> & NumOps<T> & Never<Omit<FieldOps, keyof ValueOps<T> | keyof NumOps<T>>>;
+type CompareStrValue<T> = ValueOps<T> & StrOps & Never<Omit<FieldOps, keyof ValueOps<T> | keyof StrOps>>;
+type UpdateNumValue = {
+	"$increment": number;
+};
+type JsonType = "string" | "number" | "boolean" | "object" | "array" | "null";
+type JsonCondition = JsonValue | {
+	"$eq"?: JsonValue;
+	"$ne"?: JsonValue;
+	"$not"?: JsonValue;
+	"$gt"?: number | string;
+	"$gte"?: number | string;
+	"$lt"?: number | string;
+	"$lte"?: number | string;
+	"$in"?: JsonValue[];
+	"$notIn"?: JsonValue[];
+	"$startsWith"?: string;
+	"$includes"?: string;
+	"$contains"?: JsonValue;
+	"$exists"?: boolean;
+	"$type"?: JsonType;
+};
+type JsonPathWhere = {
+	[path: string]: JsonCondition;
+};
+type CompareRefValue<T> = T | Only<"$not", T>;
+type CompareRefListValue<T> = Only<"$every", T> | Only<"$some", T> | Only<"$none", T>;
+type VectorSearch = {
+	vector: number[];
+	k?: number;
+	threshold?: number;
+};
+type FullTextSearch = string | {
+	query: string;
+	limit?: number;
+};
+type CustomSearch = Record<string, any>;
+type CustomSearchValue<P> = Only<"$near", P> | Only<"$search", P>;
+type AggregateResult<
+	TModel,
+	T
+> = (T extends {
+	$count: true;
+} ? {
+	count: number;
+} : {}) & (T extends {
+	$sum: string;
+} ? {
+	sum: number | null;
+} : {}) & (T extends {
+	$avg: string;
+} ? {
+	avg: number | null;
+} : {}) & (T extends {
+	$min: infer F;
+} ? {
+	min: (F extends keyof TModel ? TModel[F] : never) | null;
+} : {}) & (T extends {
+	$max: infer F;
+} ? {
+	max: (F extends keyof TModel ? TModel[F] : never) | null;
+} : {});
+declare const __op: unique symbol;
+type Op<T> = PromiseLike<T> & {
+	readonly [__op]: T;
+};
+type MarciOp = {
+	model: string;
+	action: string;
+	query?: any;
+	data?: any;
+	id?: any;
+	journal?: JournalArgs;
+};
+/** The arguments of a journal action (`$journalOpen` / `$journalRead` / `$journalDrop`). `wait` is in seconds. */
+type JournalArgs = {
+	name: string;
+	on?: readonly JournalOp[];
+	after?: number;
+	limit?: number;
+	wait?: number;
+};
+type MarciTransport = {
+	exec(op: MarciOp): Promise<any>;
+	batch(ops: MarciOp[]): Promise<any[]>;
+};
+type ModelTypes = {
+	name: string;
+	model: any;
+	id: Record<string, any>;
+	/** What an empty select returns: id + every scalar field, as a `{ field: true }` shape. */
+	scalars: Record<string, true>;
+	select: Record<string, any>;
+	query: Record<string, any>;
+	where: any;
+	order: Record<string, any>;
+	insert: any;
+	update: any;
+	aggregate: Record<string, any>;
+	reindex: boolean;
+};
+declare const __sub: unique symbol;
+declare const __sel: unique symbol;
+type Sub<
+	Name extends string,
+	Shape = any
+> = {
+	readonly [__sub]: Name;
+	readonly [__sel]: Shape;
+};
+type Effective<
+	T extends ModelTypes,
+	S
+> = [Exclude<keyof S, ServiceKeys>] extends [never] ? T["scalars"] : S;
+type Resolve<S> = S extends {
+	readonly [__sel]: infer X;
+} ? Resolve<X> : S extends object ? { [K in keyof S] : K extends `$${string}` ? S[K] : Resolve<S[K]> } : S;
+type Rows<
+	T extends ModelTypes,
+	Sel
+> = GetResult<T["model"], Resolve<Effective<T, Sel>>>;
+type BareId<I> = I extends {
+	id: infer V;
+} ? V : never;
+type IdArg<I> = I | BareId<I>;
+/**
+* A lazy, immutable query over one model — `db.user` itself is one. Every clause returns a new query, so
+* queries compose (`const active = db.user.where({ active: true })`). `await` runs it as `findMany`; passing
+* it to `$transaction` batches it; placing it in another query's select makes it a sub-select. `Sel` is the
+* projection: id + scalars until `select(...)` sets a shape.
+*/
+interface Query<
+	T extends ModelTypes,
+	Sel = T["scalars"]
+> extends PromiseLike<Rows<T, Sel>[]> {
+	readonly [__op]: Rows<T, Sel>[];
+	readonly [__sub]: T["name"];
+	readonly [__sel]: Effective<T, Sel>;
+	/** Filter (marcidb `$where`). Repeated calls are ANDed. */
+	where(where: T["where"]): Query<T, Sel>;
+	/** Sort by one field: `order("age", "desc")` or `order({ age: "desc" })`. */
+	order(field: keyof T["order"] & string, direction?: "asc" | "desc"): Query<T, Sel>;
+	order(order: T["order"]): Query<T, Sel>;
+	limit(n: number): Query<T, Sel>;
+	skip(n: number): Query<T, Sel>;
+	/** Keyset cursor: rows strictly after this id in the current order (`$cursor`). */
+	after(id: IdArg<T["id"]>): Query<T, Sel>;
+	/**
+	* The projection. Values are `true`, a nested shape, or a sub-query of the relation's model
+	* (`posts: db.post.limit(5)`, `posts: db.post.where({ published: true }).count()`). No argument, or no
+	* field keys, selects id + every scalar. `$`-clauses are accepted here too (the object form).
+	*/
+	select<S extends T["query"] = T["scalars"]>(shape?: S): Query<T, S>;
+	/** The first matching row or `null`. */
+	first(): Op<Rows<T, Sel> | null>;
+	/** Row count; inside a select it becomes `{ count }` for the relation. */
+	count(): Op<number> & Sub<T["name"], {
+		$count: true;
+	}>;
+	/** @deprecated pass the filter through the chain: `db.user.where(w).count()` (removed in the next minor). */
+	count(query: {
+		$where?: T["where"];
+	}): Op<number> & Sub<T["name"], {
+		$count: true;
+	}>;
+	aggregate<A extends T["aggregate"]>(query: A): Op<AggregateResult<T["model"], A>> & Sub<T["name"], NoInfer<A>>;
+	insert(data: T["insert"]): Op<T["id"]>;
+	update(id: IdArg<T["id"]>, data: T["update"]): Op<void>;
+	/** Applies `data` to every row the chain's `where` matches (all rows without one); resolves to the number of rows. */
+	updateMany(data: T["update"]): Op<number>;
+	/** @deprecated pass the filter through the chain: `db.user.where(w).updateMany(data)` (removed in the next minor). */
+	updateMany(query: {
+		$where?: T["where"];
+	}, data: T["update"]): Op<number>;
+	delete(id: IdArg<T["id"]>): Op<void>;
+	/**
+	* Deletes every row the chain's `where` matches (cascades apply, as for `delete`); resolves to the number
+	* deleted. Refuses to run without a `where` — write `.where({})` to mean "every row".
+	*/
+	deleteMany(): Op<number>;
+	/** @deprecated use `.select(query)` — it takes the same object, merged with the chain (removed in the next minor). */
+	findMany<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q>[]>;
+	/** @deprecated use `.select(query).first()` (removed in the next minor). */
+	findFirst<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q> | null>;
+}
+/** What a journal can record. Only deletes so far. */
+type JournalOp = "delete";
+/** One recorded change. `row` is the row as it last was: its id and every scalar field. */
+type JournalEntry<
+	T extends ModelTypes,
+	O extends JournalOp = JournalOp
+> = {
+	seq: number;
+	op: O;
+	row: Rows<T, T["scalars"]>;
+};
+type JournalOptions<O extends JournalOp> = {
+	/** The operations to record. A journal that exists with other ones is an error, not a redefinition. */
+	on: O | readonly O[];
+	/** `false`: the loop ends when the journal is read through. By default it waits for the next entry. */
+	wait?: boolean;
+};
+/**
+* A named, durable log of a model's changes. It starts recording when it is first asked for and keeps
+* every entry until the loop that reads it has moved past it — an entry whose loop body threw, or that
+* was never reached, is delivered again to the next reader of the same name.
+*/
+interface Journal<
+	T extends ModelTypes,
+	O extends JournalOp = JournalOp
+> extends AsyncIterable<JournalEntry<T, O>> {
+	/** Drops the journal with whatever it still holds; the model's writes stop paying for it. */
+	drop(): Promise<void>;
+}
+/**
+* `db.<model>`: the root query, plus `reindex()` for models with a `@custom` (vector / full-text) index and
+* `$journal(name, { on })` — the journal of this model's changes under that name, created on first use.
+*/
+type Collection<T extends ModelTypes> = Query<T> & (T["reindex"] extends true ? {
+	reindex(): Op<{
+		ok: boolean;
+		indexed: number;
+	}>;
+} : {}) & {
+	$journal<O extends JournalOp>(name: string, options: JournalOptions<O>): Journal<T, O>;
+};
+/** One field of a model, in slot order: `n` name, `k` key | body | one | many, `m` the relation's target model. */
+type FieldDesc = {
+	n: string;
+	k: "key" | "body" | "one" | "many";
+	t?: string | null;
+	m?: string;
+};
+/** Model name → its field descriptors (structs included, as relation targets). */
+type ModelsMeta = Record<string, readonly FieldDesc[]>;
+type QueryLayerOptions = {
+	models: ModelsMeta;
+	/** Runs one operation (a query, or a write) and resolves its result. */
+	run(op: MarciOp): Promise<any>;
+	/** Hook for `insert` payloads (the lecodes SDK generates uuid ids here). */
+	prepareInsert?(model: string, data: any): any;
+};
+/**
+* The query builder over a set of models and a `run` function. Returns `op(descriptor)` — a lazy operation
+* (`await` runs it, `$transaction` takes its `__op`) — and `collection(model)`, the immutable `db.<model>`
+* root query. Transport-agnostic: the generated client and the embedded/HTTP transports supply `run`.
+*/
+declare function createQueryLayer(options: QueryLayerOptions): {
+	op: (descriptor: MarciOp) => any;
+	collection: (model: string) => any;
+};
 declare function request(method: string, url: string, body?: any): Promise<any>;
 /**
 * A binary-eligible read over HTTP. Advertises `Accept: <binary>, json` plus the client's schema
@@ -10,12 +398,6 @@ declare function request(method: string, url: string, body?: any): Promise<any>;
 declare function requestBinary(url: string, body: any, schemaHash: string): Promise<Uint8Array | {
 	json: any;
 }>;
-type FieldDesc = {
-	n: string;
-	k: "key" | "body" | "one" | "many";
-	t?: string | null;
-	m?: string;
-};
 /**
 * Builds the binary decoder registry for a set of models. `MODELS` maps each model name to its ordered
 * field descriptors (emitted by codegen). Returns `getDecoder` (shape → cached decoder, or `null` when the
@@ -26,4 +408,4 @@ declare function createDecoderRegistry(MODELS: Record<string, FieldDesc[]>): {
 	decodeBuffer(decoder: (reader: any) => any, bytes: Uint8Array, many: boolean): any;
 };
 declare function encodeId(id: any): string;
-export { requestBinary, request, encodeId, createDecoderRegistry };
+export { AggregateKeys, AggregateResult, BareId, Collection, CompareNumValue, CompareRefListValue, CompareRefValue, CompareStrValue, CompareValue, CustomSearch, CustomSearchValue, Effective, FieldDesc, FieldOps, FullTextSearch, GetResult, IdArg, Journal, JournalArgs, JournalEntry, JournalOp, JournalOptions, JsonCondition, JsonPathWhere, JsonType, JsonValue, MarciOp, MarciTransport, ModelTypes, ModelsMeta, Never, NumOps, Only, Op, PrimitiveListUpdate, Query, QueryLayerOptions, RefListUpdate, RefListUpdateOrdered, RefListUpdateStruct, RefUpdate, RefUpdateStruct, Resolve, Rows, ServiceKeys, StrOps, Sub, UpdateNumValue, ValueOps, VectorSearch, WhereValue, createDecoderRegistry, createQueryLayer, encodeId, request, requestBinary };

package/runtime/index.js

@@ -1,3 +1,153 @@
+// src/query.ts
+var AGGREGATE_KEYS = ["$count", "$sum", "$avg", "$min", "$max"];
+var and = (a, b) => a ? b ? { $and: [a, b] } : a : b;
+function createQueryLayer(options) {
+  const { models, run } = options;
+  const op = (descriptor) => ({
+    __op: descriptor,
+    then: (onFulfilled, onRejected) => run(descriptor).then(onFulfilled, onRejected),
+    catch: (onRejected) => run(descriptor).catch(onRejected),
+    finally: (onFinally) => run(descriptor).finally(onFinally)
+  });
+  const scalarSelect = (model) => {
+    const out = {};
+    for (const f of models[model] ?? [])
+      if (f.k === "key" || f.k === "body")
+        out[f.n] = true;
+    return out;
+  };
+  const keyField = (model) => (models[model] ?? []).find((f) => f.k === "key")?.n ?? "id";
+  const idObject = (model, id) => id !== null && typeof id === "object" ? id : { [keyField(model)]: id };
+  const resolveShape = (model, shape) => {
+    const out = {};
+    let fields = 0;
+    for (const k in shape) {
+      const v = shape[k];
+      if (k.charCodeAt(0) === 36) {
+        out[k] = v;
+        continue;
+      }
+      if (v !== undefined && v !== false)
+        fields++;
+      if (v !== null && typeof v === "object") {
+        if ("__select" in v) {
+          out[k] = v.__select;
+          continue;
+        }
+        const desc = (models[model] ?? []).find((f) => f.n === k);
+        out[k] = desc && desc.m && !AGGREGATE_KEYS.some((a) => (a in v)) ? resolveShape(desc.m, v) : v;
+        continue;
+      }
+      out[k] = v;
+    }
+    if (fields === 0)
+      Object.assign(out, scalarSelect(model));
+    return out;
+  };
+  const journal = (model, name, options) => {
+    const on = Array.isArray(options.on) ? options.on : [options.on];
+    const wait = options.wait === false ? 0 : 30;
+    const opened = run({ model, action: "$journalOpen", journal: { name, on } });
+    opened.catch(() => {});
+    const read = (after, limit, wait) => run({ model, action: "$journalRead", journal: { name, after, limit, wait } });
+    return {
+      async* [Symbol.asyncIterator]() {
+        await opened;
+        let done;
+        let confirmed;
+        try {
+          for (;; ) {
+            const entries = await read(done, 100, wait);
+            confirmed = done;
+            if (entries.length === 0) {
+              if (wait === 0)
+                return;
+              continue;
+            }
+            for (const entry of entries) {
+              yield entry;
+              done = entry.seq;
+            }
+          }
+        } finally {
+          if (done !== undefined && done !== confirmed)
+            await read(done, 1, 0).catch(() => {});
+        }
+      },
+      drop: () => opened.catch(() => {}).then(() => run({ model, action: "$journalDrop", journal: { name } })).then(() => {})
+    };
+  };
+  const collection = (model) => {
+    const make = (st) => {
+      const build = (query) => {
+        const q = resolveShape(model, { ...st.shape ?? {}, ...query ?? {} });
+        const where = and(st.where, q.$where);
+        if (where)
+          q.$where = where;
+        else
+          delete q.$where;
+        if (st.order && !q.$order)
+          q.$order = st.order;
+        if (st.limit !== undefined && q.$limit === undefined)
+          q.$limit = st.limit;
+        if (st.skip !== undefined && q.$skip === undefined)
+          q.$skip = st.skip;
+        if (st.cursor !== undefined && q.$cursor === undefined)
+          q.$cursor = st.cursor;
+        return q;
+      };
+      const whereOnly = (query) => {
+        const w = and(st.where, query && query.$where);
+        return w ? { $where: w } : {};
+      };
+      const findMany = () => ({ model, action: "findMany", query: build() });
+      return {
+        get __op() {
+          return findMany();
+        },
+        get __select() {
+          return build();
+        },
+        then: (onFulfilled, onRejected) => run(findMany()).then(onFulfilled, onRejected),
+        catch: (onRejected) => run(findMany()).catch(onRejected),
+        finally: (onFinally) => run(findMany()).finally(onFinally),
+        where: (where) => make({ ...st, where: and(st.where, where) }),
+        order: (field, direction) => make({ ...st, order: typeof field === "string" ? { [field]: direction ?? "asc" } : field }),
+        limit: (n) => make({ ...st, limit: n }),
+        skip: (n) => make({ ...st, skip: n }),
+        after: (id) => make({ ...st, cursor: idObject(model, id) }),
+        select: (shape) => make({ ...st, shape: shape ?? {} }),
+        first: () => op({ model, action: "findFirst", query: build() }),
+        count: (query) => {
+          const q = whereOnly(query);
+          return Object.assign(op({ model, action: "count", query: q }), { __select: { $count: true, ...q } });
+        },
+        aggregate: (query) => {
+          const q = { ...query ?? {}, ...whereOnly(query) };
+          if (!q.$where)
+            delete q.$where;
+          return Object.assign(op({ model, action: "aggregate", query: q }), { __select: q });
+        },
+        insert: (data) => op({ model, action: "insert", data: options.prepareInsert ? options.prepareInsert(model, data) : data }),
+        update: (id, data) => op({ model, action: "update", id: idObject(model, id), data }),
+        updateMany: (a, b) => b === undefined ? op({ model, action: "updateMany", query: whereOnly(), data: a }) : op({ model, action: "updateMany", query: whereOnly(a), data: b }),
+        delete: (id) => op({ model, action: "delete", id: idObject(model, id) }),
+        deleteMany: () => {
+          if (st.where === undefined)
+            throw new Error(`marcidb: ${model}.deleteMany() needs a where — use .where({}) to delete every row`);
+          return op({ model, action: "deleteMany", query: whereOnly() });
+        },
+        reindex: () => op({ model, action: "$reindex" }),
+        $journal: (name, options) => journal(model, name, options),
+        findMany: (query) => op({ model, action: "findMany", query: build(query) }),
+        findFirst: (query) => op({ model, action: "findFirst", query: build(query) })
+      };
+    };
+    return make({});
+  };
+  return { op, collection };
+}
+
 // src/index.ts
 async function request(method, url, body) {
   const res = await fetch(url, {
@@ -227,8 +377,9 @@ function encodeId(id) {
   return String(id);
 }
 export {
-  requestBinary,
-  request,
+  createDecoderRegistry,
+  createQueryLayer,
   encodeId,
-  createDecoderRegistry
+  request,
+  requestBinary
 };