toilscript 0.1.27 → 0.1.29

package/std/assembly/toildb.ts

@@ -0,0 +1,432 @@
+// ToilDB: the developer-facing edge-database API.
+//
+// `@database class App { @collection(...) users!: Record<User, UserId>; ... }`
+// declares logical collections; the compiler (see parser `injectDatabaseBinding`)
+// synthesizes a `@global App` singleton whose fields are these typed handles,
+// resolved to numeric host handles once at module init.
+//
+// The handles marshal `@data` keys/values to the `env.data.*` host imports
+// (`bindings/toildb`). Keys and values are `@data` types (they have the injected
+// `encode(): Uint8Array` + `decodeInto(buf): void` instance methods). Both
+// encode and decode go through INSTANCE methods on the generic type parameter,
+// which AssemblyScript resolves at specialization (it cannot call the `decode`
+// static through a type parameter, but `instantiate<V>()` + `v.decodeInto(buf)`
+// works). Value types must be default-constructible.
+
+import { toildbHost } from "bindings/toildb";
+import { DataWriter } from "data";
+
+/// Resolve a `"<db>/<collection>"` name to its numeric host handle. Called once
+/// per collection at module init by the generated `App` binding.
+export function __toildbResolve(name: string): u32 {
+  const nb = Uint8Array.wrap(String.UTF8.encode(name));
+  const out = new Uint8Array(4);
+  toildbHost.resolveCollection(nb.dataStart, nb.byteLength, out.dataStart);
+  return load<u32>(out.dataStart);
+}
+
+/// Pull the last stashed variable-length result of `len` bytes into a buffer.
+function __toildbTake(len: i32): Uint8Array {
+  const buf = new Uint8Array(len);
+  toildbHost.takeResult(buf.dataStart, len);
+  return buf;
+}
+
+/// Pull a stashed result whose length is NOT known up front (e.g. the owner
+/// returned by a failed `claim`): grow the buffer until `take_result` fits.
+function __toildbTakeGrow(): Uint8Array {
+  let cap = 256;
+  let buf = new Uint8Array(cap);
+  let n = toildbHost.takeResult(buf.dataStart, cap);
+  while (n == -1) {
+    cap = cap * 2;
+    buf = new Uint8Array(cap);
+    n = toildbHost.takeResult(buf.dataStart, cap);
+  }
+  return buf.subarray(0, n);
+}
+
+/// A mutable keyed-entity collection (spec 7.1). `V` is the `@data` value type,
+/// `K` the `@data` key type.
+@global
+export class Record<V, K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// Return the record, or `null` if it does not exist.
+  get(key: K): V | null {
+    const kb = key.encode();
+    const status = toildbHost.get(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) return null;
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+
+  /// Like `get`, but traps if the record is absent.
+  require(key: K): V {
+    const v = this.get(key);
+    if (v == null) unreachable();
+    return v!;
+  }
+
+  /// Bounded multi-get: one op, one result per key (in order), each the value
+  /// or `null` if absent. The key count is capped by the request budget.
+  getMany(keys: K[]): Array<V | null> {
+    const w = new DataWriter();
+    w.writeU32(<u32>keys.length);
+    for (let i = 0, n = keys.length; i < n; i++) {
+      w.writeBytes(keys[i].encode());
+    }
+    const blob = w.toBytes();
+    const status = toildbHost.getMany(this.__handle, blob.dataStart, blob.byteLength);
+    if (status < 0) unreachable();
+    const out = __toildbTake(status);
+    const results = new Array<V | null>();
+    let off: i32 = 0;
+    const count = load<u32>(out.dataStart + off);
+    off += 4;
+    for (let i: u32 = 0; i < count; i++) {
+      const present = load<u8>(out.dataStart + off);
+      off += 1;
+      if (present == 0) {
+        results.push(null);
+        continue;
+      }
+      const len = <i32>load<u32>(out.dataStart + off);
+      off += 4;
+      const v = instantiate<V>();
+      v.decodeInto(out.subarray(off, off + len));
+      off += len;
+      results.push(v);
+    }
+    return results;
+  }
+
+  /// Whether the record exists.
+  exists(key: K): bool {
+    const kb = key.encode();
+    return toildbHost.exists(this.__handle, kb.dataStart, kb.byteLength) == 1;
+  }
+
+  /// Create the record if absent. Returns false if it already existed.
+  create(key: K, value: V): bool {
+    const kb = key.encode();
+    const vb = value.encode();
+    return toildbHost.create(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    ) == 0;
+  }
+
+  /// Apply a write through the key's home cell; returns the stored record.
+  patch(key: K, value: V): V {
+    const kb = key.encode();
+    const vb = value.encode();
+    const status = toildbHost.patch(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+    if (status < 0) unreachable();
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+
+  /// Delete the record (idempotent).
+  delete(key: K): void {
+    const kb = key.encode();
+    toildbHost.del(this.__handle, kb.dataStart, kb.byteLength, 0);
+  }
+
+  /// Atomic fetch-and-delete (consume-once); returns the prior value or `null`.
+  getDelete(key: K): V | null {
+    const kb = key.encode();
+    const status = toildbHost.getDelete(this.__handle, kb.dataStart, kb.byteLength, 0);
+    if (status < 0) return null;
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+}
+
+/// A precomputed, read-optimized projection (spec 7.2): home pages,
+/// leaderboards, rendered fragments. Read by any function kind; PUBLISHED only
+/// by a `@derive`/`@job` (the host kind gate enforces it). `V` is the `@data`
+/// value type, `K` the `@data` key type.
+@global
+export class View<V, K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// The published view for `key`, or `null` if none has been published.
+  get(key: K): V | null {
+    const kb = key.encode();
+    const status = toildbHost.viewGet(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) return null;
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+
+  /// Like `get`, but traps if no view is published.
+  require(key: K): V {
+    const v = this.get(key);
+    if (v == null) unreachable();
+    return v!;
+  }
+
+  /// 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(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+  }
+}
+
+/// The result of a `unique.claim` (spec 8.6). `claimed` is true when the caller
+/// owns the key (a fresh claim or an idempotent re-claim of its own); when
+/// false, `owner` is the value that currently holds the key.
+@global
+export class ClaimResult<V> {
+  constructor(public claimed: bool, public owner: V | null) {}
+}
+
+/// A globally-unique claim collection (spec 7.6): username, email, slug, ...
+/// `V` is the `@data` OWNER value type, `K` the `@data` claim-key type.
+@global
+export class Unique<V, K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// The value that owns `key`, or `null` if unclaimed.
+  lookup(key: K): V | null {
+    const kb = key.encode();
+    const status = toildbHost.uniqueLookup(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) return null;
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+
+  /// Claim `key` for `value`. Returns whether the caller owns it, and (when
+  /// another owns it) who.
+  claim(key: K, value: V): ClaimResult<V> {
+    const kb = key.encode();
+    const vb = value.encode();
+    const tag = toildbHost.uniqueClaim(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+    if (tag < 0) unreachable();
+    if (tag == 1) {
+      // AlreadyClaimed: the current owner is stashed.
+      const owner = instantiate<V>();
+      owner.decodeInto(__toildbTakeGrow());
+      return new ClaimResult<V>(false, owner);
+    }
+    // 0 Claimed, 2 AlreadyOwnedByCaller -> the caller owns it.
+    return new ClaimResult<V>(true, null);
+  }
+
+  /// Release `key` (only the current owner may; a non-owner release traps).
+  release(key: K, value: V): void {
+    const kb = key.encode();
+    const vb = value.encode();
+    toildbHost.uniqueRelease(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+  }
+}
+
+/// An unordered set (spec 7.3): followers, tags, ACLs, room members. `M` is the
+/// `@data` member type, `K` the `@data` set-key type.
+@global
+export class Membership<M, K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// Whether `member` is in the set keyed by `key`.
+  contains(key: K, member: M): bool {
+    const kb = key.encode();
+    const mb = member.encode();
+    return toildbHost.membershipContains(
+      this.__handle, kb.dataStart, kb.byteLength, mb.dataStart, mb.byteLength
+    ) == 1;
+  }
+
+  /// Add `member` to the set (idempotent).
+  add(key: K, member: M): void {
+    const kb = key.encode();
+    const mb = member.encode();
+    toildbHost.membershipAdd(
+      this.__handle, kb.dataStart, kb.byteLength, mb.dataStart, mb.byteLength, 0
+    );
+  }
+
+  /// Remove `member` from the set (idempotent).
+  remove(key: K, member: M): void {
+    const kb = key.encode();
+    const mb = member.encode();
+    toildbHost.membershipRemove(
+      this.__handle, kb.dataStart, kb.byteLength, mb.dataStart, mb.byteLength, 0
+    );
+  }
+
+  /// Up to `limit` members of the set. Decodes each framed member into an `M`.
+  list(key: K, limit: i32): M[] {
+    const kb = key.encode();
+    const status = toildbHost.membershipList(this.__handle, kb.dataStart, kb.byteLength, limit);
+    if (status < 0) unreachable();
+    const blob = __toildbTake(status);
+    const out = new Array<M>();
+    let off: i32 = 0;
+    const count = load<u32>(blob.dataStart + off);
+    off += 4;
+    for (let i: u32 = 0; i < count; i++) {
+      const len = <i32>load<u32>(blob.dataStart + off);
+      off += 4;
+      const m = instantiate<M>();
+      m.decodeInto(blob.subarray(off, off + len));
+      out.push(m);
+      off += len;
+    }
+    return out;
+  }
+}
+
+/// A finite, strongly-consistent resource (spec 7.7): limited stock, seats,
+/// rate grants. Reserve/confirm/cancel two-phase holds prevent oversell. `K` is
+/// the `@data` key type (the value is the host-owned escrow ledger).
+@global
+export class Capacity<K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// Units available to reserve right now.
+  available(key: K): i64 {
+    const kb = key.encode();
+    const status = toildbHost.capacityAvailable(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) unreachable();
+    return load<i64>(__toildbTake(status).dataStart);
+  }
+
+  /// Hold `amount` for `ttlMs` (it auto-releases if not confirmed in time).
+  /// Returns the reservation id (> 0), or 0 if there was not enough available
+  /// (no oversell).
+  reserve(key: K, amount: i64, ttlMs: i64): u64 {
+    const kb = key.encode();
+    const status = toildbHost.capacityReserve(
+      this.__handle, kb.dataStart, kb.byteLength, amount, ttlMs, 0
+    );
+    if (status == -2) return 0; // insufficient
+    if (status < 0) unreachable();
+    return load<u64>(__toildbTake(status).dataStart);
+  }
+
+  /// Finalize a hold into a permanent consume. Returns whether the id was valid.
+  confirm(key: K, reservationId: u64): bool {
+    const kb = key.encode();
+    return toildbHost.capacityConfirm(
+      this.__handle, kb.dataStart, kb.byteLength, reservationId as i64, 0
+    ) == 1;
+  }
+
+  /// Release a hold back to available (a confirmed sale cannot be cancelled).
+  cancel(key: K, reservationId: u64): bool {
+    const kb = key.encode();
+    return toildbHost.capacityCancel(
+      this.__handle, kb.dataStart, kb.byteLength, reservationId as i64, 0
+    ) == 1;
+  }
+
+  /// Set the ceiling (restock / reduce). `@job`/`@derive` only; the kind gate
+  /// (compile + runtime) enforces it.
+  setTotal(key: K, total: i64): void {
+    const kb = key.encode();
+    toildbHost.capacitySetTotal(this.__handle, kb.dataStart, kb.byteLength, total, 0);
+  }
+}
+
+/// A commutative integer counter (spec 7.4): likes, view counts, inventory.
+/// `K` is the `@data` key type; the value is a host-aggregated i64 rollup (there
+/// is no `set`, only `add` and `get`, so concurrent deltas never lose writes).
+@global
+export class Counter<K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// The current sum (0 if no deltas have been applied).
+  get(key: K): i64 {
+    const kb = key.encode();
+    const status = toildbHost.counterGet(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) unreachable();
+    const buf = __toildbTake(status);
+    return load<i64>(buf.dataStart);
+  }
+
+  /// Apply a (possibly negative) delta; saturates at the i64 bounds.
+  add(key: K, delta: i64): void {
+    const kb = key.encode();
+    toildbHost.counterAdd(this.__handle, kb.dataStart, kb.byteLength, delta, 0);
+  }
+}
+
+/// 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 Events<V, K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// Append an event to the stream.
+  append(key: K, event: V): void {
+    const kb = key.encode();
+    const eb = event.encode();
+    toildbHost.append(this.__handle, kb.dataStart, kb.byteLength, eb.dataStart, eb.byteLength, 0);
+  }
+
+  /// The newest `limit` events, newest first. Decodes each framed event into a
+  /// `V`. The host frames them as `u32 count` then per event `u32 len + bytes`.
+  latest(key: K, limit: i32): V[] {
+    const kb = key.encode();
+    const status = toildbHost.latest(this.__handle, kb.dataStart, kb.byteLength, limit);
+    if (status < 0) unreachable();
+    const blob = __toildbTake(status);
+    const out = new Array<V>();
+    let off: i32 = 0;
+    const count = load<u32>(blob.dataStart + off);
+    off += 4;
+    for (let i: u32 = 0; i < count; i++) {
+      const len = <i32>load<u32>(blob.dataStart + off);
+      off += 4;
+      const ev = instantiate<V>();
+      ev.decodeInto(blob.subarray(off, off + len));
+      out.push(ev);
+      off += len;
+    }
+    return out;
+  }
+}

package/std/assembly/toilscript.d.ts

@@ -85,6 +85,102 @@ declare function auth(target: Object, propertyKey: string | symbol, descriptor:
 /** Declare the authenticated-user type (`@user class User { ... }`); enables `AuthService.getUser()`. */
 declare function user(target: Function): void;
 
+// --- ToilDB (@database / @collection + the @query/@action/... function kinds),
+//     handled natively by the compiler; typed here so editors accept the bare forms ---
+
+/** Marks a class as a ToilDB database: each `@collection` field becomes a typed,
+ *  lazily-resolved collection handle (`App.users.get(...)`). */
+declare function database(target: Function): void;
+
+/** Declares a `@database` field as a collection - a `Record`/`View`/`Unique`/
+ *  `Counter`/`Events`/`Membership`/`Capacity` handle. */
+declare function collection(target: Object, propertyKey: string | symbol): void;
+
+/** ToilDB function kinds (spec 6) - the data ops a function may issue. `@query`
+ *  is read-only; `@action` adds bounded writes/claims; `@derive` publishes
+ *  views/rollups; `@job` is background work; `@admin` is control-plane only. The
+ *  compiler enforces the family x kind matrix (a `@query` calling `.patch` is a
+ *  compile error). */
+declare function query(target: Function): void;
+declare function action(target: Function): void;
+declare function job(target: Function): void;
+declare function derive(target: Function): void;
+declare function admin(target: Function): void;
+
+// The ToilDB collection HANDLES are ambient globals (no import) - the compiler
+// provides them (`std/assembly/toildb`, `@global`); these typings let editors
+// recognize `@collection users!: Record<User, UserId>` and `App.users.get(...)`.
+// `K`/`V`/`M` are `@data` types (the binary codec the host marshals).
+
+/** A mutable keyed-entity collection (spec 7.1): user profiles, items, sessions. */
+declare class Record<V, K> {
+  get(key: K): V | null;
+  require(key: K): V;
+  exists(key: K): bool;
+  getMany(keys: K[]): (V | null)[];
+  create(key: K, value: V): bool;
+  patch(key: K, value: V): V;
+  delete(key: K): void;
+  getDelete(key: K): V | null;
+}
+
+/** A precomputed, read-optimized projection (spec 7.2): pages, leaderboards. */
+declare class View<V, K> {
+  get(key: K): V | null;
+  require(key: K): V;
+  publish(key: K, value: V): void;
+}
+
+/** The result of a `unique.claim` (spec 8.6). */
+declare class ClaimResult<V> {
+  claimed: bool;
+  owner: V | null;
+  constructor(claimed: bool, owner: V | null);
+}
+
+/** A globally-unique claim collection (spec 7.6): usernames, emails, slugs. */
+declare class Unique<V, K> {
+  lookup(key: K): V | null;
+  claim(key: K, value: V): ClaimResult<V>;
+  release(key: K, value: V): void;
+}
+
+/** An unordered set (spec 7.3): followers, tags, ACLs, room members. */
+declare class Membership<M, K> {
+  contains(key: K, member: M): bool;
+  add(key: K, member: M): void;
+  remove(key: K, member: M): void;
+  list(key: K, limit: i32): M[];
+}
+
+/** A finite, strongly-consistent resource via escrow (spec 7.7): stock, seats. */
+declare class Capacity<K> {
+  available(key: K): i64;
+  reserve(key: K, amount: i64, ttlMs: i64): u64;
+  confirm(key: K, reservationId: u64): bool;
+  cancel(key: K, reservationId: u64): bool;
+  setTotal(key: K, total: i64): void;
+}
+
+/** A commutative integer counter (spec 7.4): likes, view counts, inventory. */
+declare class Counter<K> {
+  get(key: K): i64;
+  add(key: K, delta: i64): void;
+}
+
+/** An append-only event log (spec 7.5): activity feeds, audit trails. */
+declare class Events<V, K> {
+  append(key: K, event: V): void;
+  latest(key: K, limit: i32): V[];
+}
+
+// The handles are ambient (no import needed), but `import { Counter } from
+// 'toildb'` is also accepted for editors that prefer explicit imports - it just
+// re-exports the same globals.
+declare module 'toildb' {
+  export { Record, View, Unique, ClaimResult, Membership, Capacity, Counter, Events };
+}
+
 // Big integers, native globals implemented in std/assembly/bignum. The
 // arithmetic/bitwise/comparison operators
 // (+ - * / % & | ^ << >> == != < > <= >=) are operator overloads resolved by