toilscript 0.1.63 → 0.1.64

package/dist/web.js

@@ -1,8 +1,8 @@
-var ASSEMBLYSCRIPT_VERSION = "0.1.63";
+var ASSEMBLYSCRIPT_VERSION = "0.1.64";
   var ASSEMBLYSCRIPT_IMPORTMAP = {
   "imports": {
-    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.63/dist/toilscript.js",
-    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.63/dist/cli.js",
+    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.64/dist/toilscript.js",
+    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.64/dist/cli.js",
     "binaryen": "https://cdn.jsdelivr.net/npm/binaryen@130.0.0/index.js",
     "long": "https://cdn.jsdelivr.net/npm/long@5.3.2/index.js"
   }

package/package.json

@@ -8,7 +8,7 @@
     "toilscript",
     "wasm"
   ],
-  "version": "0.1.63",
+  "version": "0.1.64",
   "author": "Daniel Wirtz <dcode+assemblyscript@dcode.io>",
   "license": "Apache-2.0",
   "homepage": "https://github.com/dacely-cloud/toilscript",
@@ -81,7 +81,7 @@
     "prepublishOnly": "node scripts/build",
     "watch": "node scripts/build --watch",
     "coverage": "npx c8 -- npm test",
-    "test": "npm run test:parser && npm run test:compiler -- --parallel && npm run test:browser && npm run test:toilconfig && npm run test:transform && npm run test:cli && npm run test:json && npm run test:data && npm run test:dbresolve && npm run test:dbstatic && npm run test:dbtypes && npm run test:routekinds && npm run test:derive && npm run test:streams && npm run test:daemon && npm run test:dberror && npm run test:events && npm run test:uniquebatch",
+    "test": "npm run test:parser && npm run test:compiler -- --parallel && npm run test:browser && npm run test:toilconfig && npm run test:transform && npm run test:cli && npm run test:json && npm run test:data && npm run test:dbresolve && npm run test:dbstatic && npm run test:dbtypes && npm run test:routekinds && npm run test:derive && npm run test:streams && npm run test:daemon && npm run test:dberror && npm run test:events && npm run test:uniquebatch && npm run test:membership && npm run test:event-redaction",
     "test:parser": "node --enable-source-maps tests/parser",
     "test:compiler": "node --enable-source-maps --no-warnings tests/compiler",
     "test:browser": "node --enable-source-maps tests/browser",
@@ -98,6 +98,8 @@
     "test:routekinds": "node tests/routekinds/run.mjs",
     "test:derive": "node tests/derive/run.mjs",
     "test:streams": "node tests/streams/run.mjs && node tests/streams/catalog.mjs && node tests/streams/codegen.mjs",
+    "test:membership": "node tests/membership/run.mjs",
+    "test:event-redaction": "node tests/event-redaction/run.mjs",
     "test:daemon": "node tests/daemon/run.mjs",
     "test:uniquebatch": "node tests/uniquebatch/run.mjs",
     "test:events": "node tests/events/run.mjs",

package/std/assembly/bindings/toildb.ts

@@ -71,6 +71,24 @@ export namespace toildbHost {
     idemPtr: usize
   ): i32;
 
+  // Caller-observed byte CAS: expectedLen=-1 expects absence. 1 applied, 0 mismatch.
+  // @ts-ignore: decorator
+  @external("env", "data.compare_exchange")
+  export declare function compareExchange(
+    handle: u32, keyPtr: usize, keyLen: i32,
+    expectedPtr: usize, expectedLen: i32, valPtr: usize, valLen: i32
+  ): i32;
+
+  // @ts-ignore: decorator
+  @external("env", "data.compare_delete")
+  export declare function compareDelete(
+    handle: u32, keyPtr: usize, keyLen: i32, expectedPtr: usize, expectedLen: i32
+  ): i32;
+
+  // @ts-ignore: decorator
+  @external("env", "data.get_current")
+  export declare function getCurrent(handle: u32, keyPtr: usize, keyLen: i32): i32;
+
   // record.upsert -> 0 created | 1 updated | 2 @unique-conflict (not written) |
   // negative error. A single blind last-writer-wins put: creates the row if
   // absent, overwrites it if present, in ONE op (no create-then-patch round trip).
@@ -141,6 +159,11 @@ export namespace toildbHost {
     idemPtr: usize
   ): i32;
 
+  // Remove a view key (Action/Derive/Job), idempotently.
+  // @ts-ignore: decorator
+  @external("env", "data.view_delete")
+  export declare function viewDelete(handle: u32, keyPtr: usize, keyLen: i32, idemPtr: usize): i32;
+
   // membership.contains -> 1 present | 0 absent | negative error.
   // @ts-ignore: decorator
   @external("env", "data.membership_contains")
@@ -168,6 +191,13 @@ export namespace toildbHost {
   @external("env", "data.membership_list")
   export declare function membershipList(handle: u32, setPtr: usize, setLen: i32, limit: i32): i32;
 
+  // Ordered membership page: list frame + optional length-prefixed raw cursor.
+  // @ts-ignore: decorator
+  @external("env", "data.membership_page")
+  export declare function membershipPage(
+    handle: u32, setPtr: usize, setLen: i32, cursorPtr: usize, cursorLen: i32, limit: i32
+  ): i32;
+
   // capacity.set_total(total: i64) -> 0 ok | negative error (job/derive only).
   // @ts-ignore: decorator
   @external("env", "data.capacity_set_total")
@@ -232,6 +262,16 @@ export namespace toildbHost {
 
   // Point reads: stashed value length | -2 absent | typed negative error.
   // result_schema_version exposes the stored event's schema version.
+  // @ts-ignore: decorator
+  @external("env", "data.events_reference")
+  export declare function eventsReference(handle: u32, keyPtr: usize, keyLen: i32, idPtr: usize, idLen: i32): i32;
+  // @ts-ignore: decorator
+  @external("env", "data.events_redact")
+  export declare function eventsRedact(handle: u32, keyPtr: usize, keyLen: i32, sequence: u64, hlc: u64): i32;
+  // @ts-ignore: decorator
+  @external("env", "data.events_entries")
+  export declare function eventsEntries(handle: u32, keyPtr: usize, keyLen: i32, limit: i32, after: u64): i32;
+
   // @ts-ignore: decorator
   @external("env", "data.events_get")
   export declare function eventsGet(handle: u32, keyPtr: usize, keyLen: i32, evidPtr: usize, evidLen: i32): i32;

package/std/assembly/log.ts

@@ -0,0 +1,14 @@
+// Structured server logging, available to request, stream, and daemon code.
+@external("env", "server_log")
+declare function __serverLog(level: i32, ptr: usize, len: i32): i32;
+
+@global
+export class Log {
+  private static write(level: i32, message: string): bool {
+    const bytes = Uint8Array.wrap(String.UTF8.encode(message));
+    return __serverLog(level, bytes.dataStart, bytes.byteLength) == 1;
+  }
+  static info(message: string): bool { return Log.write(0, message); }
+  static warn(message: string): bool { return Log.write(1, message); }
+  static error(message: string): bool { return Log.write(2, message); }
+}

package/std/assembly/toildb.ts

@@ -233,6 +233,14 @@ export enum UpsertResult {
   Conflict = 2,
 }
 
+/// An observed value plus its original storage bytes (before decoding/migration).
+/// Keep the snapshot unchanged while constructing a replacement value.
+@global
+export class DocumentSnapshot<V> {
+  constructor(public value: V, public encoded: Uint8Array) {}
+}
+
+@global
 export class Documents<K, V> {
   private __handle: u32;
 
@@ -259,6 +267,47 @@ export class Documents<K, V> {
     return v;
   }
 
+  /// Read without rewrite-on-read. Retains the exact bytes for conditional writes,
+  /// including records whose codec or schema migrated during decoding.
+  getSnapshot(key: K): DocumentSnapshot<V> | null {
+    const kb = key.encode();
+    const status = toildbHost.get(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) { __toildbMiss(status); return null; }
+    const bytes = __toildbTake(status);
+    const value = instantiate<V>();
+    value.decodeInto(bytes);
+    return new DocumentSnapshot<V>(value, bytes);
+  }
+
+  /// Owner-authoritative snapshot, bypassing replica and request caches.
+  getCurrentSnapshot(key: K): DocumentSnapshot<V> | null {
+    const kb = key.encode();
+    const status = toildbHost.getCurrent(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) { __toildbMiss(status); return null; }
+    const bytes = __toildbTake(status);
+    const value = instantiate<V>();
+    value.decodeInto(bytes);
+    return new DocumentSnapshot<V>(value, bytes);
+  }
+
+  compareExchangeSnapshot(key: K, expected: DocumentSnapshot<V> | null, value: V): bool {
+    const kb = key.encode();
+    const vb = value.encode();
+    const eb = expected == null ? new Uint8Array(0) : expected.encoded;
+    const status = toildbHost.compareExchange(this.__handle, kb.dataStart, kb.byteLength,
+      eb.dataStart, expected == null ? -1 : eb.byteLength, vb.dataStart, vb.byteLength);
+    if (status < 0) abort("ToilDB compareExchange failed: status " + status.toString(), "toildb", 0, 0);
+    return status == 1;
+  }
+
+  compareDeleteSnapshot(key: K, expected: DocumentSnapshot<V>): bool {
+    const kb = key.encode();
+    const eb = expected.encoded;
+    const status = toildbHost.compareDelete(this.__handle, kb.dataStart, kb.byteLength, eb.dataStart, eb.byteLength);
+    if (status < 0) abort("ToilDB compareDelete failed: status " + status.toString(), "toildb", 0, 0);
+    return status == 1;
+  }
+
   /// Like `get`, but traps if the record is absent.
   require(key: K): V {
     const v = this.get(key);
@@ -276,7 +325,13 @@ export class Documents<K, V> {
     }
     const blob = w.toBytes();
     const status = toildbHost.getMany(this.__handle, blob.dataStart, blob.byteLength);
-    if (status < 0) unreachable();
+    if (status < 0) {
+      __toildbMiss(status);
+      abort("ToilDB getMany failed: status " + status.toString() +
+        "; DbError=" + (<i32>Db.lastError()).toString() +
+        "; keys=" + keys.length.toString() +
+        ". Query accepts 32 keys, Action 64, background 1024; split larger batches.", "toildb", 0, 0);
+    }
     const out = __toildbTake(status);
     const results = new Array<V | null>();
     let off: i32 = 0;
@@ -354,6 +409,21 @@ export class Documents<K, V> {
     return v;
   }
 
+  /// Replace only if the stored bytes equal `expected`; null expects absence.
+  /// Returns false on a mismatch. Routed to the owner; @unique values are rejected.
+  compareExchange(key: K, expected: V | null, value: V): bool {
+    const kb = key.encode();
+    const vb = value.encode();
+    const eb = expected == null ? new Uint8Array(0) : expected.encode();
+    const status = toildbHost.compareExchange(
+      this.__handle, kb.dataStart, kb.byteLength,
+      eb.dataStart, expected == null ? -1 : eb.byteLength,
+      vb.dataStart, vb.byteLength
+    );
+    if (status < 0) abort("ToilDB compareExchange failed: status " + status.toString(), "toildb", 0, 0);
+    return status == 1;
+  }
+
   /// Submit a replacement of an EXISTING record: true when accepted, false on
   /// absence or rejection. The ABI carries no caller-observed version or value,
   /// so this cannot protect a read-modify-write based on an earlier application read.
@@ -363,10 +433,16 @@ export class Documents<K, V> {
     return toildbHost.enqueue(this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0) == 0;
   }
 
+  /// Delete only when the stored bytes still equal the caller's expectation.
+  compareDelete(key: K, expected: V): bool {
+    return this.compareDeleteSnapshot(key, new DocumentSnapshot<V>(expected, expected.encode()));
+  }
+
   /// Delete the record (idempotent).
   delete(key: K): void {
     const kb = key.encode();
-    toildbHost.del(this.__handle, kb.dataStart, kb.byteLength, 0);
+    const status = toildbHost.del(this.__handle, kb.dataStart, kb.byteLength, 0);
+    if (status < 0) abort("ToilDB delete failed: status " + status.toString(), "toildb", 0, 0);
   }
 
   /// Atomic fetch-and-delete (consume-once); returns the prior value or `null`.
@@ -409,14 +485,22 @@ export class View<K, V> {
     return v!;
   }
 
+  /// Remove a projection key. Delete its source personal data before rebuilding.
+  delete(key: K): void {
+    const kb = key.encode();
+    const status = toildbHost.viewDelete(this.__handle, kb.dataStart, kb.byteLength, 0);
+    if (status < 0) abort("ToilDB view.delete failed: status " + status.toString(), "toildb", 0, 0);
+  }
+
   /// Publish (overwrite) the view for `key`. Derive/job only; the host assigns
   /// the version so a later publish always supersedes an earlier one.
   publish(key: K, value: V): void {
     const kb = key.encode();
     const vb = value.encode();
-    toildbHost.viewPublish(
+    const status = toildbHost.viewPublish(
       this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
     );
+    if (status < 0) abort("ToilDB view.publish failed: status " + status.toString(), "toildb", 0, 0);
   }
 }
 
@@ -483,6 +567,17 @@ export class Unique<K, V> {
   }
 }
 
+/// A page in encoded-member order; pass cursor to listPage to continue.
+@global
+export class MembershipPage<M> {
+  members: M[];
+  cursor: Uint8Array | null;
+  constructor(members: M[], cursor: Uint8Array | null) {
+    this.members = members;
+    this.cursor = cursor;
+  }
+}
+
 /// An unordered set (spec 7.3): followers, tags, ACLs, room members. `M` is the
 /// `@data` member type, `K` the `@data` set-key type.
 @global
@@ -520,6 +615,36 @@ export class Membership<K, M> {
     );
   }
 
+  /// Read members strictly after an opaque cursor. A full page may require an
+  /// empty final page to establish the end. Pagination is not a snapshot.
+  listPage(key: K, limit: i32, cursor: Uint8Array | null = null): MembershipPage<M> {
+    const kb = key.encode();
+    const cb = cursor == null ? new Uint8Array(0) : cursor;
+    const status = toildbHost.membershipPage(
+      this.__handle, kb.dataStart, kb.byteLength, cb.dataStart,
+      cursor == null ? -1 : cb.byteLength, limit
+    );
+    if (status < 0) abort("ToilDB membership.listPage failed: status " + status.toString(), "toildb", 0, 0);
+    const blob = __toildbTake(status);
+    const out = new Array<M>();
+    let off: i32 = 4;
+    const count = load<u32>(blob.dataStart);
+    for (let i: u32 = 0; i < count; i++) {
+      const version = <i64>load<u32>(blob.dataStart + off); off += 4;
+      const len = <i32>load<u32>(blob.dataStart + off); off += 4;
+      const member = instantiate<M>();
+      member.decodeIntoVersioned(blob.subarray(off, off + len), version);
+      out.push(member); off += len;
+    }
+    const hasCursor = load<u8>(blob.dataStart + off); off++;
+    let next: Uint8Array | null = null;
+    if (hasCursor != 0) {
+      const len = <i32>load<u32>(blob.dataStart + off); off += 4;
+      next = blob.slice(off, off + len);
+    }
+    return new MembershipPage<M>(out, next);
+  }
+
   /// Up to `limit` members of the set. Decodes each framed member into an `M`.
   list(key: K, limit: i32): M[] {
     const kb = key.encode();
@@ -944,6 +1069,21 @@ export class Analytics {
 /// An append-only event log (spec 7.5): activity feeds, audit trails, the
 /// fact stream a `@derive` consumes. `V` is the `@data` event type, `K` the
 /// `@data` stream-key type.
+@global
+export class EventRef {
+  constructor(public sequence: u64 = 0, public hlc: u64 = 0) {}
+}
+
+@global
+export class EventEntry<V> {
+  constructor(public reference: EventRef, public value: V) {}
+}
+
+@global
+export class EventPage<V> {
+  constructor(public entries: Array<EventEntry<V>>, public cursor: u64, public hasMore: bool) {}
+}
+
 @global
 export class Events<K, V> {
   private __handle: u32;
@@ -952,6 +1092,49 @@ export class Events<K, V> {
     this.__handle = handle;
   }
 
+  /// Read an appendOnce reference, including during pending cleanup. No payload is returned.
+  reference(key: K, eventId: string): EventRef | null {
+    const kb = key.encode();
+    const id = Uint8Array.wrap(String.UTF8.encode(eventId));
+    const status = toildbHost.eventsReference(this.__handle, kb.dataStart, kb.byteLength, id.dataStart, id.byteLength);
+    if (status < 0) { __toildbMiss(status); return null; }
+    const reader = new DataReader(__toildbTake(status));
+    const reference = new EventRef(reader.readU64(), reader.readU64());
+    if (!reader.ok) abort("Invalid event reference", "toildb", 0, 0);
+    return reference;
+  }
+
+  /// Erase this entry and one bounded page of recovery copies. Repeat in later
+  /// background calls until true. The payload is hidden from the first successful call.
+  redact(key: K, reference: EventRef): bool {
+    const kb = key.encode();
+    const status = toildbHost.eventsRedact(this.__handle, kb.dataStart, kb.byteLength, reference.sequence, reference.hlc);
+    if (status < 0) abort("ToilDB events.redact failed: status " + status.toString(), "toildb", 0, 0);
+    return status == 1;
+  }
+
+  /// Bounded, oldest-first page with references for ordinary and appendOnce events.
+  /// Keep the opaque cursor and use hasMore even if an erased page is empty.
+  entries(key: K, limit: i32 = 128, after: u64 = 0): EventPage<V> {
+    const kb = key.encode();
+    const status = toildbHost.eventsEntries(this.__handle, kb.dataStart, kb.byteLength, limit, after);
+    if (status < 0) abort("ToilDB events.entries failed: status " + status.toString(), "toildb", 0, 0);
+    const reader = new DataReader(__toildbTake(status));
+    const count = reader.readU32();
+    const entries = new Array<EventEntry<V>>();
+    for (let i: u32 = 0; i < count; i++) {
+      const reference = new EventRef(reader.readU64(), reader.readU64());
+      const version = <i64>reader.readU32();
+      const bytes = reader.readBytes();
+      const value = instantiate<V>(); value.decodeIntoVersioned(bytes, version);
+      entries.push(new EventEntry<V>(reference, value));
+    }
+    const hasMore = reader.readU8() != 0;
+    const cursor: u64 = hasMore ? reader.readU64() : 0;
+    if (!reader.ok) abort("Invalid event page", "toildb", 0, 0);
+    return new EventPage<V>(entries, cursor, hasMore);
+  }
+
   /// Read an event by its appendOnce eventId, or null if absent. Bounded request-path read.
   get(key: K, eventId: string): V | null {
     const kb = key.encode();

package/std/assembly/toilscript.d.ts

@@ -240,6 +240,12 @@ declare const enum UpsertResult {
 }
 
 /** A mutable keyed-entity collection (spec 7.1): user profiles, items, sessions. */
+declare class DocumentSnapshot<V> {
+  value: V;
+  encoded: Uint8Array;
+  constructor(value: V, encoded: Uint8Array);
+}
+
 declare class Documents<K, V> {
   get(key: K): V | null;
   require(key: K): V;
@@ -247,6 +253,14 @@ declare class Documents<K, V> {
   getMany(keys: K[]): (V | null)[];
   create(key: K, value: V): bool;
   patch(key: K, value: V): V;
+  /** Replace if stored bytes equal expected; null expects absence. Owner-cell only,
+   *  rejects @unique values. False on mismatch; other failures abort. */
+  compareExchange(key: K, expected: V | null, value: V): bool;
+  compareDelete(key: K, expected: V): bool;
+  getSnapshot(key: K): DocumentSnapshot<V> | null;
+  getCurrentSnapshot(key: K): DocumentSnapshot<V> | null;
+  compareExchangeSnapshot(key: K, expected: DocumentSnapshot<V> | null, value: V): bool;
+  compareDeleteSnapshot(key: K, expected: DocumentSnapshot<V>): bool;
   /** Create-or-overwrite in one op (blind last-writer-wins); replaces the two-op
    *  `if (!create(k,v)) patch(k,v)` idiom. Right for writing a whole value; wrong
    *  for read-modify-write of accumulating state (a balance/count), where a
@@ -265,6 +279,7 @@ declare class Documents<K, V> {
 declare class View<K, V> {
   get(key: K): V | null;
   require(key: K): V;
+  delete(key: K): void;
   publish(key: K, value: V): void;
 }
 
@@ -284,12 +299,20 @@ declare class Unique<K, V> {
   release(key: K, value: V): void;
 }
 
+/** A page in encoded-member byte order, with an opaque continuation cursor. */
+declare class MembershipPage<M> {
+  members: M[];
+  cursor: Uint8Array | null;
+  constructor(members: M[], cursor: Uint8Array | null);
+}
+
 /** An unordered set (spec 7.3): followers, tags, ACLs, room members. */
 declare class Membership<K, M> {
   contains(key: K, member: M): bool;
   add(key: K, member: M): void;
   remove(key: K, member: M): void;
   list(key: K, limit: i32): M[];
+  listPage(key: K, limit: i32, cursor?: Uint8Array | null): MembershipPage<M>;
 }
 
 /** A finite, strongly-consistent resource via escrow (spec 7.7): stock, seats. */
@@ -308,7 +331,17 @@ declare class Counter<K> {
 }
 
 /** An append-only event log (spec 7.5): activity feeds, audit trails. */
+declare class EventRef {
+  sequence: u64;
+  hlc: u64;
+  constructor(sequence?: u64, hlc?: u64);
+}
+declare class EventEntry<V> { reference: EventRef; value: V; constructor(reference: EventRef, value: V); }
+declare class EventPage<V> { entries: EventEntry<V>[]; cursor: u64; hasMore: bool; constructor(entries: EventEntry<V>[], cursor: u64, hasMore: bool); }
 declare class Events<K, V> {
+  reference(key: K, eventId: string): EventRef | null;
+  redact(key: K, reference: EventRef): bool;
+  entries(key: K, limit?: i32, after?: u64): EventPage<V>;
   /** Read an event by its appendOnce eventId, or null if absent. */
   get(key: K, eventId: string): V | null;
   /** Read the newest appended event, or null for an empty stream. */
@@ -872,3 +905,11 @@ declare class JSON {
   /** Serialize this value tree to a JSON string. */
   toString(): string;
 }
+
+/** Server logging. At most 4096 UTF-8 bytes/message, 32 messages per call.
+ *  Returns false when the message allowance is exhausted. */
+declare class Log {
+  static info(message: string): bool;
+  static warn(message: string): bool;
+  static error(message: string): bool;
+}