marcidb-client 0.14.0 → 0.15.0

package/package.json

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

package/runtime/index.d.ts

@@ -207,6 +207,8 @@ type MarciOp = {
 	query?: any;
 	data?: any;
 	id?: any;
+	key?: any;
+	onInsert?: any;
 	journal?: JournalArgs;
 };
 /** The arguments of a journal action (`$journalOpen` / `$journalRead` / `$journalDrop`). `wait` is in seconds. */
@@ -275,9 +277,11 @@ interface Query<
 	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" })`. */
+	/** Sort: `order("age", "desc")` or `order({ age: "desc" })`. A second `order()` adds the next key — ties on
+	*  the first are broken by it (`order("createdAt", "desc").order("id")`); the keys may also come as an array
+	*  in one call. Several keys sort in memory. */
 	order(field: keyof T["order"] & string, direction?: "asc" | "desc"): Query<T, Sel>;
-	order(order: T["order"]): Query<T, Sel>;
+	order(order: T["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`). */
@@ -302,7 +306,26 @@ interface Query<
 	}>;
 	aggregate<A extends T["aggregate"]>(query: A): Op<AggregateResult<T["model"], A>> & Sub<T["name"], NoInfer<A>>;
 	insert(data: T["insert"]): Op<T["id"]>;
+	/** The new row by `select`'s shape — its defaults, dates and files as stored: one call, nothing to read back. */
+	insert<S extends T["query"]>(data: T["insert"], options: {
+		select: S;
+	}): Promise<Rows<T, S>>;
 	update(id: IdArg<T["id"]>, data: T["update"]): Op<void>;
+	/** Writes the row `key` names — the id, or the fields of ONE unique index (a `@unique` field, all the fields of
+	*  a `@unique(<name>)` group): an update of `data` when it exists, an insert of key + data when not. `data` is
+	*  in the insert form (plain values, `{ id }` for a relation; no `$` operators). `onInsert` adds fields used
+	*  only when the row is created. Resolves to the id, like `insert`. */
+	upsert<K extends Partial<T["insert"]> | T["id"]>(key: K, data: Omit<T["insert"], keyof K>, options?: {
+		onInsert?: Partial<T["insert"]>;
+	}): Op<T["id"]>;
+	/** The row written, by `select`'s shape — as stored, whichever path the upsert took. */
+	upsert<
+		K extends Partial<T["insert"]> | T["id"],
+		S extends T["query"]
+	>(key: K, data: Omit<T["insert"], keyof K>, options: {
+		onInsert?: Partial<T["insert"]>;
+		select: S;
+	}): Promise<Rows<T, S>>;
 	/** 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). */
@@ -376,6 +399,9 @@ type QueryLayerOptions = {
 	run(op: MarciOp): Promise<any>;
 	/** Hook for `insert` payloads (the lecodes SDK generates uuid ids here). */
 	prepareInsert?(model: string, data: any): any;
+	/** Hook for the `onInsert` part of an `upsert` — the fields used only when the row is created (the lecodes SDK
+	*  puts a uuid id here). Receives what the caller gave (or undefined), returns what is sent. */
+	prepareUpsert?(model: string, onInsert: any): any;
 };
 /**
 * The query builder over a set of models and a `run` function. Returns `op(descriptor)` — a lazy operation
@@ -386,6 +412,17 @@ declare function createQueryLayer(options: QueryLayerOptions): {
 	op: (descriptor: MarciOp) => any;
 	collection: (model: string) => any;
 };
+/** The class of a refused request — the server's `kind`: a constraint (`unique`, `foreign_key`, `restrict`,
+*  `duplicate_id`), `not_found`, `bad_request`, `unauthorized`, or `internal` for a fault of the server. */
+type MarciErrorKind = "unique" | "foreign_key" | "restrict" | "duplicate_id" | "not_found" | "bad_request" | "unauthorized" | "internal";
+/** A failed request: `kind` is what to switch on, `field` the `Model.field` a constraint is about, the message is for a person. */
+declare class MarciError extends Error {
+	name: "MarciError";
+	readonly status: number;
+	readonly kind: MarciErrorKind;
+	readonly field?: string;
+	constructor(status: number, message: string, kind: MarciErrorKind, field?: string);
+}
 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
@@ -408,4 +445,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 { 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 };
+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, MarciError, MarciErrorKind, 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

@@ -101,6 +101,11 @@ function createQueryLayer(options) {
         return w ? { $where: w } : {};
       };
       const findMany = () => ({ model, action: "findMany", query: build() });
+      const readBack = (written, select) => written.then((id) => run({ model, action: "findFirst", query: resolveShape(model, { ...select, $where: id }) })).then((row) => {
+        if (row === null)
+          throw new Error(`marcidb: ${model}: the row just written is gone`);
+        return row;
+      });
       return {
         get __op() {
           return findMany();
@@ -112,7 +117,12 @@ function createQueryLayer(options) {
         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 }),
+        order: (field, direction) => {
+          const given = typeof field === "string" ? [{ [field]: direction ?? "asc" }] : Array.isArray(field) ? field : Object.entries(field).map(([k, v]) => ({ [k]: v }));
+          const prev = st.order === undefined ? [] : Array.isArray(st.order) ? st.order : [st.order];
+          const keys = [...prev, ...given];
+          return make({ ...st, order: keys.length === 1 ? keys[0] : keys });
+        },
         limit: (n) => make({ ...st, limit: n }),
         skip: (n) => make({ ...st, skip: n }),
         after: (id) => make({ ...st, cursor: idObject(model, id) }),
@@ -128,8 +138,16 @@ function createQueryLayer(options) {
             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 }),
+        insert: (data, extra) => {
+          const inserted = op({ model, action: "insert", data: options.prepareInsert ? options.prepareInsert(model, data) : data });
+          return extra?.select ? readBack(inserted, extra.select) : inserted;
+        },
         update: (id, data) => op({ model, action: "update", id: idObject(model, id), data }),
+        upsert: (key, data, o) => {
+          const onInsert = options.prepareUpsert ? options.prepareUpsert(model, o?.onInsert) : o?.onInsert;
+          const written = op({ model, action: "upsert", key, data, ...onInsert !== undefined ? { onInsert } : {} });
+          return o?.select ? readBack(written, o.select) : written;
+        },
         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: () => {
@@ -149,16 +167,36 @@ function createQueryLayer(options) {
 }
 
 // src/index.ts
+class MarciError extends Error {
+  name = "MarciError";
+  status;
+  kind;
+  field;
+  constructor(status, message, kind, field) {
+    super(message);
+    this.status = status;
+    this.kind = kind;
+    this.field = field;
+  }
+}
+var kindOfStatus = (status) => status === 404 ? "not_found" : status === 401 ? "unauthorized" : status >= 500 ? "internal" : "bad_request";
+async function failure(res) {
+  const text = await res.text();
+  try {
+    const body = JSON.parse(text);
+    if (body && typeof body.error === "string")
+      return new MarciError(res.status, body.error, body.kind ?? kindOfStatus(res.status), body.field);
+  } catch {}
+  return new MarciError(res.status, text || `HTTP ${res.status}`, kindOfStatus(res.status));
+}
 async function request(method, url, body) {
   const res = await fetch(url, {
     method,
     headers: { "Content-Type": "application/json" },
     body: body !== undefined ? JSON.stringify(body) : undefined
   });
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`MarciDB [${res.status}]: ${text}`);
-  }
+  if (!res.ok)
+    throw await failure(res);
   return res.json();
 }
 var BINARY_MEDIA_TYPE = "application/x-marcidb-rows";
@@ -172,10 +210,8 @@ async function requestBinary(url, body, schemaHash) {
     },
     body: JSON.stringify(body ?? {})
   });
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`MarciDB [${res.status}]: ${text}`);
-  }
+  if (!res.ok)
+    throw await failure(res);
   const contentType = res.headers.get("content-type") ?? "";
   if (contentType.includes(BINARY_MEDIA_TYPE)) {
     return new Uint8Array(await res.arrayBuffer());
@@ -377,6 +413,7 @@ function encodeId(id) {
   return String(id);
 }
 export {
+  MarciError,
   createDecoderRegistry,
   createQueryLayer,
   encodeId,