marcidb-client 0.13.0 → 0.14.0

package/package.json

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

package/runtime/index.d.ts

@@ -207,6 +207,15 @@ type MarciOp = {
 	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>;
@@ -311,13 +320,47 @@ interface Query<
 	/** @deprecated use `.select(query).first()` (removed in the next minor). */
 	findFirst<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q> | null>;
 }
-/** `db.<model>`: the root query, plus `reindex()` for models with a `@custom` (vector / full-text) index. */
+/** 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;
@@ -365,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, createQueryLayer, createDecoderRegistry, WhereValue, VectorSearch, ValueOps, UpdateNumValue, Sub, StrOps, ServiceKeys, Rows, Resolve, RefUpdateStruct, RefUpdate, RefListUpdateStruct, RefListUpdateOrdered, RefListUpdate, QueryLayerOptions, Query, PrimitiveListUpdate, Op, Only, NumOps, Never, ModelsMeta, ModelTypes, MarciTransport, MarciOp, JsonValue, JsonType, JsonPathWhere, JsonCondition, IdArg, GetResult, FullTextSearch, FieldOps, FieldDesc, Effective, CustomSearchValue, CustomSearch, CompareValue, CompareStrValue, CompareRefValue, CompareRefListValue, CompareNumValue, Collection, BareId, AggregateResult, AggregateKeys };
+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

@@ -44,6 +44,39 @@ function createQueryLayer(options) {
       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) => {
@@ -105,6 +138,7 @@ function createQueryLayer(options) {
           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) })
       };
@@ -343,9 +377,9 @@ function encodeId(id) {
   return String(id);
 }
 export {
-  requestBinary,
-  request,
-  encodeId,
+  createDecoderRegistry,
   createQueryLayer,
-  createDecoderRegistry
+  encodeId,
+  request,
+  requestBinary
 };