toilscript 0.1.57 → 0.1.58

package/dist/web.js

@@ -1,8 +1,8 @@
-var ASSEMBLYSCRIPT_VERSION = "0.1.57";
+var ASSEMBLYSCRIPT_VERSION = "0.1.58";
   var ASSEMBLYSCRIPT_IMPORTMAP = {
   "imports": {
-    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.57/dist/toilscript.js",
-    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.57/dist/cli.js",
+    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.58/dist/toilscript.js",
+    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.58/dist/cli.js",
     "binaryen": "https://cdn.jsdelivr.net/npm/binaryen@130.0.0-nightly.20260609/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.57",
+  "version": "0.1.58",
   "author": "Daniel Wirtz <dcode+assemblyscript@dcode.io>",
   "license": "Apache-2.0",
   "homepage": "https://github.com/dacely-cloud/toilscript",

package/std/assembly/bindings/toildb.ts

@@ -71,6 +71,20 @@ export namespace toildbHost {
     idemPtr: usize
   ): 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).
+  // @ts-ignore: decorator
+  @external("env", "data.upsert")
+  export declare function upsert(
+    handle: u32,
+    keyPtr: usize,
+    keyLen: i32,
+    valPtr: usize,
+    valLen: i32,
+    idemPtr: usize
+  ): i32;
+
   // record.delete -> 0 ok | negative error.
   // @ts-ignore: decorator
   @external("env", "data.delete")

package/std/assembly/toildb.ts

@@ -75,6 +75,18 @@ function __toildbTakeGrow(): Uint8Array {
 /// A mutable keyed-entity collection (spec 7.1). `V` is the `@data` value type,
 /// `K` the `@data` key type.
 @global
+/// The outcome of `Documents.upsert` (spec 8.3). The wire bytes are pinned in the
+/// host ABI (`data.upsert`): a non-negative tag the guest returns as-is.
+export enum UpsertResult {
+  /// The row did not exist and was created.
+  Created = 0,
+  /// The row already existed and was overwritten.
+  Updated = 1,
+  /// A `@unique` field value is already owned by a DIFFERENT record; nothing was
+  /// written (the only outcome an upsert cannot auto-resolve).
+  Conflict = 2,
+}
+
 export class Documents<K, V> {
   private __handle: u32;
 
@@ -158,6 +170,30 @@ export class Documents<K, V> {
     ) == 0;
   }
 
+  /// Create-or-overwrite in ONE op (spec 8.3): a blind last-writer-wins put that
+  /// creates the row if absent or overwrites it if present, replacing the two-op
+  /// `if (!create(k,v)) patch(k,v)` idiom. Returns `UpsertResult.Created` or
+  /// `.Updated`; on a `@unique` collection, `.Conflict` when the value's unique
+  /// field is already held by ANOTHER record (nothing is written).
+  ///
+  /// The write is blind: it stores `value` as-is, so concurrent upserts do not
+  /// conflict or retry - the later one wins and overwrites the earlier. Correct
+  /// for writing a whole value (a profile, a settings blob); wrong for a
+  /// read-modify-write of accumulating state (a balance, a like count), where a
+  /// concurrent write would be lost - use `counter.add` or version-checked
+  /// `patch` there. A lost write is a data-integrity concern, not a boundary one:
+  /// the key is tenant-scoped, so a race is only ever one tenant's own concurrent
+  /// writes, and `@unique` stays race-safe (claim-once at the value's home).
+  upsert(key: K, value: V): UpsertResult {
+    const kb = key.encode();
+    const vb = value.encode();
+    const status = toildbHost.upsert(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+    if (status < 0) unreachable();
+    return <UpsertResult>status;
+  }
+
   /// Apply a write through the key's home cell; returns the stored record.
   patch(key: K, value: V): V {
     const kb = key.encode();

package/std/assembly/toilscript.d.ts

@@ -229,6 +229,16 @@ declare function admin(target: Object, propertyKey: string | symbol, descriptor:
 // User>` and `App.users.get(...)`. Every handle is KEY-FIRST (`<K, V>`, matching
 // `Map`/`Record`). `K`/`V`/`M` are `@data` types (the codec the host marshals).
 
+/** The outcome of `Documents.upsert` (spec 8.3). */
+declare const enum UpsertResult {
+  /** The row did not exist and was created. */
+  Created = 0,
+  /** The row already existed and was overwritten. */
+  Updated = 1,
+  /** A `@unique` field value is already owned by another record; nothing written. */
+  Conflict = 2,
+}
+
 /** A mutable keyed-entity collection (spec 7.1): user profiles, items, sessions. */
 declare class Documents<K, V> {
   get(key: K): V | null;
@@ -237,6 +247,13 @@ declare class Documents<K, V> {
   getMany(keys: K[]): (V | null)[];
   create(key: K, value: V): bool;
   patch(key: K, value: V): V;
+  /** 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
+   *  concurrent write would be lost - use `counter.add` or version-checked
+   *  `patch` there. The key is tenant-scoped, so a race is only ever the same
+   *  tenant's own writes. See {@link UpsertResult}. */
+  upsert(key: K, value: V): UpsertResult;
   delete(key: K): void;
   getDelete(key: K): V | null;
 }