teptris 0.3.21 → 0.3.22

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.22",
   "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;