@poe-platform/safe-js 0.1.37 → 0.1.38

package/README.md

@@ -241,7 +241,7 @@ const collection = context.createHostObject({ indexed: {
 
 Saved collections observe current host contents. Index reads, `Object.keys`/`values`/`entries`, `Object.hasOwn`, `in`, `for...in`, `for...of`, array/object spread and `Array.from` use the live view. Enumerable keys include current indices and fixed members, but not `length`. `Array.from` preserves element identity and interleaves mapping with reads. Noncanonical and out-of-range indices never call `get`; fixed members cannot reuse `length` or canonical index names. Enumeration and traversal consume execution budgets, without eagerly allocating virtual properties.
 
-For changing named properties, add `named` to the same definition:
+For a live set of named properties, add `named` to the same definition:
 
 ```js
 const named = {
@@ -258,13 +258,36 @@ const attributesObject = context.createHostObject({ named });
 | --- | --- |
 | `keys()` | Synchronous dense own-data array of distinct strings. Proxies, accessors, sparse arrays and reserved `constructor`/`prototype`/`__proto__` names reject. |
 | `get(name)` | Synchronous value provider, called only for a currently present name. Existing host conversion and identity rules apply. |
+| `set(name, value)` | Optional synchronous setter, including new names. Receives the normally converted host value; assignment returns the original guest RHS. Omit to keep named writes disabled. |
+| `delete(name)` | Optional synchronous deleter returning a boolean. Absent names return `true` without calling it; existing names return its result. Omit to keep deletion disabled. |
 | `maxKeys` | Required positive integer, at most 65,536. |
 | `maxKeyCodeUnits` | Required positive aggregate key-length cap, at most 1,048,576 UTF-16 code units. Execution, array, string and data budgets also apply. |
 | `enumerable` | Defaults to `true`. Set `false` to keep names readable and visible to `in`/`Object.hasOwn`, but omit them from keys/values/entries, object spread and `for...in`. |
 
 Fixed properties/methods take precedence over names. With `indexed`, numeric indices and `length` remain indexed members. Enumeration deduplicates collisions; names removed by an earlier getter are skipped. Named-only objects are not iterable—combine `named` with `indexed` when you need numeric collection access and `for...of`.
 
-Named properties, indexed members and indexed `length` are read-only. Live objects reject deletion, freezing, native prototype access, property-descriptor manipulation and portable serialization. Realm state is not a checkpoint: snapshot/replay and live-capability error-data conversion are rejected. Extensions are trusted native code; grants are a registration contract, not OS isolation. Native work still needs host timeouts and external process supervision for hard limits. No DOM, timers or browser engine are bundled.
+To opt into dynamic writes and deletion, supply the hooks explicitly:
+
+```js
+const storage = context.createHostObject({
+  named: {
+    keys: () => [...values.keys()],
+    get: name => values.get(name),
+    set: (name, value) => { values.set(name, value); },
+    delete: name => values.delete(name),
+    maxKeys: 256,
+    maxKeyCodeUnits: 8192
+  }
+});
+```
+
+Guest code can now use `storage.theme = "dark"` and `delete storage.theme`.
+
+Both hooks must be synchronous; async/generator functions and proxies reject, and promises returned by ordinary functions are rejected and observed. Fixed members still use only their declared setters. Named hooks cannot overwrite or delete fixed members, indexed slots (including out-of-range indices), indexed `length`, or reserved prototype names. Saved objects remain live across native changes and are revoked on realm close.
+
+SafeJS validates current keys and prospective new-key count/UTF-16/data limits before calling a mutator, then validates keys again afterward. Work, conversion and cancellation budgets still apply. Providers must enforce atomic storage quotas themselves: a post-write failure cannot roll back native side effects. Values are normally copied or passed as explicit realm-owned capabilities, not retained as arbitrary guest objects. Browser Storage coercion, persistence, origin policy and events belong in the consumer.
+
+Named properties are read-only unless opted in; indexed members and indexed `length` remain read-only. Live objects reject other deletion, freezing, native prototype access, property-descriptor manipulation and portable serialization. Realm state is not a checkpoint: snapshot/replay and live-capability error-data conversion are rejected. Extensions are trusted native code; grants are a registration contract, not OS isolation. Native work still needs host timeouts and external process supervision for hard limits. No DOM, timers or browser engine are bundled.
 
 For one-shot use, `run(source, { extensions, grants, ... })` accepts the same realm options plus `filename`, returns data only, and closes resources before settling. Run-only features such as snapshots, `entryPointArgs`, `importMeta`, custom random generators and telemetry are rejected in this mode rather than silently ignored.
 

package/dist/safe-js/chunks/{chunk-LBJGHXII.js → chunk-BW4SYRDC.js}

@@ -6380,11 +6380,15 @@ function createLiveHostObject(definition, controller) {
   if (input.named !== void 0) {
     const data = readDataRecord(input.named, "Named host capability");
     if (Object.keys(data).some(
-      (key) => !["keys", "get", "maxKeys", "maxKeyCodeUnits", "enumerable"].includes(key)
+      (key) => !["keys", "get", "set", "delete", "maxKeys", "maxKeyCodeUnits", "enumerable"].includes(key)
     ))
       throw new TypeError("Unknown named host capability field.");
-    if (typeof data.keys !== "function" || typeof data.get !== "function")
-      throw new TypeError("Named keys and get must be synchronous functions.");
+    for (const name of ["keys", "get", "set", "delete"]) {
+      const operation = data[name];
+      if (operation === void 0 && (name === "set" || name === "delete")) continue;
+      if (typeof operation !== "function" || types3.isProxy(operation) || types3.isAsyncFunction(operation) || types3.isGeneratorFunction(operation))
+        throw new TypeError(`Named ${name} must be a synchronous non-generator function, not a proxy.`);
+    }
     if (typeof data.maxKeys !== "number" || !Number.isInteger(data.maxKeys) || data.maxKeys < 1 || data.maxKeys > MAX_NAMED_KEYS)
       throw new RangeError(`Named maxKeys must be an integer from 1 to ${MAX_NAMED_KEYS}.`);
     if (typeof data.maxKeyCodeUnits !== "number" || !Number.isInteger(data.maxKeyCodeUnits) || data.maxKeyCodeUnits < 1 || data.maxKeyCodeUnits > MAX_NAMED_KEY_CODE_UNITS)
@@ -6396,6 +6400,8 @@ function createLiveHostObject(definition, controller) {
     named = {
       keys: data.keys,
       get: data.get,
+      set: data.set,
+      delete: data.delete,
       maxKeys: data.maxKeys,
       maxKeyCodeUnits: data.maxKeyCodeUnits,
       enumerable: data.enumerable
@@ -6519,8 +6525,28 @@ function setHostObjectMember(value, key, entry) {
   state.controller.assertActive();
   state.controller.chargeWork();
   const property = state.properties.get(key);
-  if (property?.set === void 0) throw new TypeError(`Host property '${key}' is not writable.`);
-  state.controller.write(property.set, entry);
+  if (property !== void 0) {
+    if (property.set === void 0) throw new TypeError(`Host property '${key}' is not writable.`);
+    state.controller.write(property.set, entry);
+    return;
+  }
+  if (state.named?.set === void 0) throw new TypeError(`Host property '${key}' is not writable.`);
+  namedMutationKeys(state, key, true);
+  state.controller.write((value2) => state.named.set(key, value2), entry);
+  namedKeys(state);
+}
+function deleteHostObjectMember(value, key) {
+  const state = guestObjects.get(value);
+  state.controller.assertActive();
+  state.controller.chargeWork();
+  if (state.named?.delete === void 0) throw new TypeError("Live host properties cannot be deleted.");
+  if (!namedMutationKeys(state, key, false).includes(key)) return true;
+  const deleted = state.controller.read(() => state.named.delete(key), (result) => {
+    if (typeof result !== "boolean") throw new TypeError("Named delete must return a boolean.");
+    return result;
+  });
+  namedKeys(state);
+  return deleted;
 }
 function getHostObjectKeys(value) {
   const state = guestObjects.get(value);
@@ -6591,6 +6617,27 @@ function canonicalIndex(key) {
   const index = Number(key);
   return Number.isInteger(index) && index >= 0 && index < 4294967295 && String(index) === key ? index : void 0;
 }
+function namedMutationKeys(state, key, create) {
+  state.controller.chargeWork(key.length);
+  state.controller.checkString(key);
+  if (["constructor", "prototype", "__proto__"].includes(key) || state.properties.has(key) || state.methods.has(key) || state.indexed !== void 0 && (key === "length" || canonicalIndex(key) !== void 0))
+    throw new TypeError(`Host member '${key}' is protected from named mutation.`);
+  const named = state.named;
+  if (key.length > named.maxKeyCodeUnits)
+    throw new RangeError("Named key exceeds maximum UTF-16 code units.");
+  const keys = namedKeys(state);
+  if (create && !keys.includes(key)) {
+    const length = keys.length + 1;
+    if (length > named.maxKeys) throw new RangeError("Named keys exceed maxKeys.");
+    state.controller.checkLength(length);
+    let units = key.length;
+    for (const existing of keys) units += existing.length;
+    if (units > named.maxKeyCodeUnits)
+      throw new RangeError("Named keys exceed maximum UTF-16 code units.");
+    state.controller.checkTemporaryDataSize(1 + length + units);
+  }
+  return keys;
+}
 function namedKeys(state) {
   const named = state.named;
   return state.controller.read(named.keys, (value) => {
@@ -27141,11 +27188,11 @@ async function evaluateDeleteExpression(node, context) {
   if (!isIndexableSandboxValue(member.object)) {
     throw new TypeError("Unary operator 'delete' requires a sandbox object property.");
   }
-  deleteSandboxProperty(member.object, member.property);
+  const deleted = deleteSandboxProperty(member.object, member.property);
   return {
     kind: "normal",
     hasValue: true,
-    value: true
+    value: deleted
   };
 }
 async function evaluateUpdateExpression(node, context) {
@@ -28007,12 +28054,12 @@ function setSandboxProperty(target, property, value, budget) {
   }
 }
 function deleteSandboxProperty(target, property) {
-  if (isGuestHostObject(target)) throw new TypeError("Live host properties cannot be deleted.");
+  if (isGuestHostObject(target)) return deleteHostObjectMember(target, String(property));
   if (isGuestClosure(target)) target = materializeFunctionProperties(target);
   if (Array.isArray(target)) {
     assertCollectionMutable(target);
   }
-  delete target[String(property)];
+  return delete target[String(property)];
 }
 function getClosureMemberValue(target, property, context) {
   return getFunctionMember(target, property, createFunctionMethodOptions(context));
@@ -31052,6 +31099,9 @@ var RealmState = class {
       assertActive: this.assertOpen,
       chargeWork: this.chargeWork,
       checkLength: (length) => this.budget.allocateArrayLength(length),
+      checkString: (value) => {
+        this.budget.allocateString(value);
+      },
       checkTemporaryDataSize: (size) => {
         const temporary = {};
         try {
@@ -31064,7 +31114,7 @@ var RealmState = class {
         const value = this.invokeHost(operation, operation);
         if (types5.isPromise(value)) {
           void Promise.resolve(value).catch(() => void 0);
-          throw new TypeError("Live property getters must be synchronous.");
+          throw new TypeError("Live property operations must be synchronous.");
         }
         return this.importValue(validate === void 0 ? value : validate(value));
       },
@@ -32693,4 +32743,4 @@ export {
   FileSnapshotBackend,
   run
 };
-//# sourceMappingURL=chunk-LBJGHXII.js.map
+//# sourceMappingURL=chunk-BW4SYRDC.js.map