teptris 0.3.21 → 0.3.23

package/README.md

@@ -16,6 +16,7 @@ const teptris = await init();
 teptris.loads('a = 1');               // → { a: 1 }
 teptris.dump(obj);                    // → canonical TOML string
 teptris.dumpJson(obj);                // → natural JSON string
+teptris.edit(src, "serve.port", "9090"); // → the file with ONE value rewritten
 teptris.engineVersion();              // → the libteptris inside
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teptris",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "TOML for JavaScript/TypeScript at libteptris speed (WebAssembly, no fallback) - version tracks the engine ({engine}.{iteration}; npm semver is 3-part)",
   "type": "module",
   "main": "src/index.js",

package/src/index.d.ts

@@ -61,6 +61,28 @@ export interface TeptrisApi {
   /** The libteptris engine version inside this build. */
   engineVersion(): string;
 
+  /** Parse TOML into a retained engine document (no host objects):
+   *  the LOSSLESS round-trip surface. JS numbers cannot carry TOML's
+   *  int/float distinction (loads' documented floor) - doc handles
+   *  can: dumpDoc(loadsDoc(s)) re-emits the parsed tree exactly, at
+   *  C speed with nothing materialized in JS. Single slot: a later
+   *  loadsDoc replaces the held document. */
+  loadsDoc(toml: string): TeptrisDoc;
+
+  /** Emit a loadsDoc() document back to canonical TOML — the
+   *  lossless half of the doc round-trip. */
+  dumpDoc(doc: TeptrisDoc): string;
+
+  /** Format-preserving edit: rewrite exactly the value bytes of one
+   *  key = value line; every other byte of the source survives
+   *  (comments, blank lines, formatting, CRLF endings). keyPath may
+   *  carry a [table] prefix ("t.x" edits x inside [t]); a dotted key
+   *  line may continue the open section. replacement is the value's
+   *  TEXT, validated by the engine; multiline strings and inline
+   *  collections splice (parse-verified). Throws Error on an absent
+   *  key or a malformed span/replacement. */
+  edit(source: string, keyPath: string, replacement: string): string;
+
   /** Compile a descriptor plan (once) — materialize only the planned
    *  keys of any document via planWalk. Rows: a string name is a
    *  scalar; kind "collection" walks an array; kind "raw" takes the
@@ -76,6 +98,13 @@ export interface TeptrisApi {
   planFree(plan: number): void;
 }
 
+/** An opaque retained-document handle from {@link TeptrisApi.loadsDoc}
+ *  (single slot: a later loadsDoc replaces the held document). */
+export interface TeptrisDoc {
+  /** Renders "[teptris doc]". */
+  toString(): string;
+}
+
 /** One planned key of a {@link PlanRowSpec} tree. */
 export interface PlanRowSpec {
   name: string;

package/src/index.js

@@ -10,6 +10,21 @@ function cstr(mod, s) {
   return ptr;
 }
 
+// The len-bounded fast path: TextEncoder.encodeInto writes UTF-8
+// STRAIGHT into the wasm heap with the native encoder, replacing
+// emscripten's two JS-loop passes (lengthBytesUTF8 + stringToUTF8) -
+// the measured biggest JS-side cost of the loads crossing. Only for
+// entry points whose C side takes an explicit length (no NUL needed);
+// NUL-terminated destinations keep cstr.
+const utf8Encoder = new TextEncoder();
+
+function cstrLen(mod, s) {
+  const cap = s.length * 3 + 4; /* UTF-8 worst case: 3 bytes/unit */
+  const ptr = mod._teptris_wasm_alloc(cap);
+  const { written } = utf8Encoder.encodeInto(s, mod.HEAPU8.subarray(ptr, ptr + cap));
+  return { ptr, len: written };
+}
+
 function freeCstr(mod, ptr) { mod._teptris_wasm_free(ptr); }
 
 // RFC 3339-ish (the four TOML shapes) back into builder fields
@@ -148,8 +163,8 @@ export function initApi(mod) {
     if (typeof toml !== "string") {
       throw new TypeError("loads expects a string");
     }
-    const ptr = cstr(mod, toml);
-    const st = mod._teptris_wasm_load(ptr, lengthBytesUTF8(toml));
+    const { ptr, len } = cstrLen(mod, toml);
+    const st = mod._teptris_wasm_load(ptr, len);
     let value = null, error = null;
     if (st === 0) {
       const jptr = mod._teptris_wasm_json();
@@ -428,8 +443,8 @@ export function initApi(mod) {
     if (typeof toml !== "string") {
       throw new TypeError("loadsDoc expects a string");
     }
-    const ptr = cstr(mod, toml);
-    const st = mod._teptris_wasm_load_doc(ptr, lengthBytesUTF8(toml));
+    const { ptr, len } = cstrLen(mod, toml);
+    const st = mod._teptris_wasm_load_doc(ptr, len);
     freeCstr(mod, ptr);
     if (st !== 0) {
       docHeld = false;
@@ -567,8 +582,8 @@ export function initApi(mod) {
     if (typeof toml !== "string") {
       throw new TypeError("planWalk expects a TOML string");
     }
-    const p = cstr(mod, toml);
-    const st = mod._teptris_wasm_plan_walk(plan, p, lengthBytesUTF8(toml));
+    const { ptr: p, len: plen } = cstrLen(mod, toml);
+    const st = mod._teptris_wasm_plan_walk(plan, p, plen);
     freeCstr(mod, p);
     if (st !== 0) {
       throw planError();
@@ -594,11 +609,11 @@ export function initApi(mod) {
         throw new TypeError("edit expects three strings");
       }
     }
-    const sp = cstr(mod, source);
+    const { ptr: sp, len: slen } = cstrLen(mod, source);
     const kp = cstr(mod, keyPath);
     const rp = cstr(mod, replacement);
     let out = null, error = null;
-    const st = mod._teptris_wasm_edit(sp, lengthBytesUTF8(source), kp, rp);
+    const st = mod._teptris_wasm_edit(sp, slen, kp, rp);
     if (st === 0) {
       const optr = mod._teptris_wasm_json();
       const olen = mod._teptris_wasm_json_len();