@doxsync/core 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -6,18 +6,20 @@ state. JavaScript provides loading and a small synchronous API.
 
 ## Build from this repository
 
-Install Rust, Node.js 22+, and `wasm-pack`, then run:
+Install Rust, Node.js 22.12+ (or 24+), and `wasm-pack`, then run:
 
 ```sh
 rustup target add wasm32-unknown-unknown
 cd doxsync-js
+npm ci
 npm run build
 node examples/node.mjs
 ```
 
 `npm run build` runs `wasm-pack` in release mode with the locked Cargo
-dependencies and the `wasm` feature, then copies the JS wrapper and declarations
-into `dist/`. There are no npm runtime dependencies. To create a local npm
+dependencies and the `wasm` feature, then builds the TypeScript wrapper with Vite in library mode.
+`vite-plugin-dts` generates type declarations in `dist/`. The runtime dependency
+`decimal.js` supplies exact JS decimal values. To create a local npm
 tarball, run `npm pack`; it builds first and includes the WASM artifact.
 Installing that tarball does not require Rust or wasm-pack.
 
@@ -37,10 +39,10 @@ also generate the JS glue required to load it.
 After installing the package from the local tarball:
 
 ```js
-import { init, Producer, Consumer } from "@doxsync/core";
+import { init, Producer, Consumer, supportedProtocols } from "@doxsync/core";
 
 await init();
-const producer = new Producer({ count: 1n, ratio: 0.5 }, [1]);
+const producer = new Producer({ count: 1n, ratio: 0.5 }, supportedProtocols());
 const consumer = new Consumer();
 
 try {
@@ -77,13 +79,16 @@ provide garbage-collection cleanup, but its timing is not deterministic.
 
 ## WASM initialization
 
-Call and await `init()` before creating either class. Initialization is the
+Call and await `init()` before creating either class or calling
+`supportedProtocols()`. Initialization is the
 only asynchronous operation. Concurrent calls share the first call's promise
 and source; successful initialization is reused, and failed initialization
 can be retried.
 
 - Browsers fetch the WASM next to the generated JS. Serve `dist/` over HTTP;
   retain the `dist/wasm/` directory and serve `.wasm` as `application/wasm`.
+  When loading without a bundler, provide an import map for `decimal.js`;
+  `examples/browser.html` maps it to the local npm installation.
 - Node.js uses the package's conditional export to read the same packaged
   WASM from disk. Browser entry points contain no Node.js imports.
 - `init(source)` also accepts a URL string, `URL`, `ArrayBuffer`, `Uint8Array`,
@@ -117,6 +122,7 @@ CommonJS entry point or polyfills are supplied.
 | `null`, `boolean`, `string` | Null, Bool, UTF-8 text |
 | `number` | Float, including `-0`, NaN, and infinities |
 | `bigint` | Int in `[-2^64, 2^64 - 1]` |
+| `Decimal` from `decimal.js` | Exact Decimal with a 96-bit coefficient and scale 0–28 |
 | `Uint8Array` (including Node Buffer) | Binary string, copied |
 | Dense arrays | Arrays, copied recursively |
 | Plain or null-prototype objects | Maps with string keys |
@@ -135,8 +141,8 @@ Unsupported values are rejected: `undefined`, functions, symbols (including
 enumerable symbol map keys), sparse arrays, cyclic references, accessor
 properties used as document values, out-of-range integers, unpaired UTF-16
 surrogates in strings or keys, and objects such as Date, Map, Set, or class
-instances. Use values from the same JS realm as the library; custom prototypes
-and proxies are not supported as a document model.
+instances other than Decimal. Use values from the same JS realm as the library;
+custom prototypes and proxies are not supported as a document model.
 
 Rust and conversion errors are JS `Error` instances with `kind` equal to
 `Internal`, `InvalidData`, or `UnexpectedType`. Initialization, lifecycle,
@@ -151,29 +157,111 @@ try {
 }
 ```
 
-The JS package exposes only `init`, `Producer`, and `Consumer` at runtime.
+The JS package exposes `init`, `supportedProtocols`, `Producer`, `Consumer`, and `Decimal`
+at runtime.
 Rust's lower-level Document, Value, and Message APIs remain internal to this
 binding, and the wire protocol is shared with native Rust.
 
+### Decimal values
+
+```js
+import { init, Producer, Consumer, Decimal, supportedProtocols } from "@doxsync/core";
+
+await init();
+const producer = new Producer({ price: new Decimal("12.34") }, supportedProtocols());
+const consumer = new Consumer();
+try {
+  consumer.consumeDiff(producer.produceDiff());
+  console.log(consumer.document().price.toFixed(2)); // "12.34"
+} finally {
+  producer.free();
+  consumer.free();
+}
+```
+
+Pass decimal strings to the Decimal constructor to avoid introducing binary
+floating-point rounding before synchronization. Instances imported directly from
+`decimal.js` or created by `Decimal.clone()` are also accepted. Values must be
+finite and exactly representable using a sign and a 96-bit unsigned coefficient
+divided by `10^scale`, with scale from 0 through 28. Invalid values throw `InvalidData`;
+conversion never silently rounds. Input `number` values remain Float values.
+
+Protocol 2 returns decimal.js instances, constructed independently of the user's
+global decimal.js configuration with 29 significant digits of arithmetic
+precision and an exponent range of -100 through 100. Their initial values are
+exact. Arithmetic follows decimal.js precision rules; synchronization does not
+implement arithmetic or recover precision already lost by the caller.
+
+Rust preserves scale: `Decimal::from_str_exact("1.20")` remains distinct from
+`Decimal::from_str_exact("1.2")` when wrapped with `Value::decimal`. It also
+provides `as_decimal`, `as_decimal_and_modify`, and `value!` conversions for owned
+or borrowed Decimal values. Negative zero is normalized without changing scale.
+JS decimal.js instances do not retain trailing zeros: a Rust value of `1.20`
+read through `document()` and sent back through JS may become `1.2`.
+
+With a protocol 1 producer (`new Producer(value, [1])`), decimals arrive as
+ordinary strings. Rust preserves the source scale in those strings; JS can only
+send the scale still present in its decimal.js value. Strings are never
+automatically parsed as decimals. Switching between a Decimal and its identical
+fallback string produces no change under protocol 1.
+
 ### Protocol negotiation
 
+Call `supportedProtocols()` after `await init()` to get all protocol versions
+supported by the local build, currently `[1, 2]`. Each call returns an independent
+ordinary `number[]`; modifying it does not affect subsequent calls or the engine.
+No producer or consumer instance is needed. Rust callers can use
+`doxsync::supported_protocols() -> &'static [u32]` without initialization.
+
+For peers running in separate processes, have the consumer advertise its list
+and pass that received list to the producer. The examples above use the local
+list because both peers share the same build. This query reports supported
+versions, not the version negotiated for an individual stream.
+
 The second `Producer` constructor argument is required: pass an array of protocol
 versions supported by the consumer, such as `[1]`. Versions must be integers in
 `[0, 2^32 - 1]`. The producer selects the highest version supported by both peers;
-order and duplicates do not matter. Currently only version `1` is implemented.
+order and duplicates do not matter. Versions `1` and `2` are implemented.
 Empty or incompatible lists, omitted arguments, and invalid values throw an error
 with `kind: "InvalidData"`.
 
 The first packed message starts its metadata with protocol instruction `2` followed
-by the selected version, currently `1`; both are unsigned variable-length integers.
+by the selected version; both are unsigned variable-length integers.
 Later messages omit this declaration and retain the same protocol for the stream.
 The consumer rejects first messages without a leading protocol declaration,
 unsupported versions, and repeated declarations. Legacy messages without version
-metadata are no longer accepted. Both peers must be upgraded together.
+metadata are not accepted. Existing protocol 1 peers can continue to receive
+updates, with decimals represented as strings.
 
 Failed encoding or consumption preserves protocol initialization state as well as
 pool state, allowing retries. Keep and deliver packed messages in order as usual.
 
+### Decimal wire encoding
+
+Protocol 2 represents `sign × coefficient × 10^-scale`. The first byte's high
+nibble is `0x9` for nonnegative decimals or `0xA` for negative decimals; `0x6`
+remains reserved. Its low nibble directly contains scales 0–14. A low nibble of
+`0xF` is followed by one byte containing the complete scale, 15–28.
+
+The absolute coefficient follows as minimal unsigned LEB128: seven data bits
+per byte, least significant group first, with the high bit indicating continuation.
+Zero uses one `00` byte. There is no ZigZag transform or negative offset.
+Coefficients occupy 1–14 bytes and must fit in 96 bits. The fourteenth byte
+must have its continuation bit clear and contain at most `0x1F`.
+
+| Value | Hex bytes (excluding the message header) |
+| --- | --- |
+| `0.01` | `92 01` |
+| `1.20` | `92 78` |
+| `12.34` | `92 D2 09` |
+| `-12.34` | `A2 D2 09` |
+| `0.00` | `92 00` |
+| `0.000000000000001` | `9F 0F 01` |
+
+The maximum value encoding length is 16 bytes. Decoders reject negative zero,
+non-minimal coefficients, invalid scales, overflow, truncation, and Decimal
+tags in protocol 1. Existing Int encoding is unchanged.
+
 ### Path key encoding
 
 Protocol v1 path definitions use the low two bits of each segment's unsigned
@@ -191,3 +279,31 @@ through message encoding and are resolved when the consumer reads the definition
 
 This extends v1 directly. Both peers must be upgraded together: older decoders
 reject the new `0b10` path segment tag.
+
+### Compact floating-point values
+
+Protocol 2 encodes numbers as binary16, binary32, or
+binary64, choosing the shortest representation that preserves the original
+binary64 bits. Decoded values remain JavaScript numbers. Signed zero is
+preserved; NaNs retain binary64 encoding. Protocol 1 continues to use
+binary64 for every number.
+
+### Binary value reuse
+
+Protocol 2 pools binary values by content, so repeated `Uint8Array` values can
+share a compact reference within a message and across subsequent messages.
+Producers admit payloads from 16 bytes through 64 KiB, using up to 256 slots
+and at most 1 MiB of definitions per message. Values that cannot be admitted
+remain inline. The first definition has an overhead, so pooling does not make
+every message smaller.
+
+The Rust pool shares immutable payload storage. Each `document()` conversion
+still returns independent `Uint8Array` copies: modifying one field cannot change
+another field, the consumer's document, or a later message.
+
+This extends unreleased protocol 2 without adding a version. New consumers accept
+earlier v2 messages, but earlier v2 consumers cannot read binary pool definitions
+or references. Upgrade both v2 peers together; explicitly select `[1]` when
+communicating with an implementation that lacks this extension. Version
+negotiation alone cannot distinguish these v2 builds. Protocol 1 continues to
+encode binary values inline.

package/dist/decimal.d.ts

@@ -0,0 +1,3 @@
+import { Decimal } from 'decimal.js';
+export declare function decimalToString(value: unknown): string | undefined;
+export declare function decimalFromString(value: string): Decimal;

package/dist/index.d.ts

@@ -1,64 +1,11 @@
-/** Numbers are floats; bigint values are integers in [-2^64, 2^64 - 1]. */
-export type SyncValue =
-  | null
-  | boolean
-  | string
-  | number
-  | bigint
-  | Uint8Array
-  | SyncValue[]
-  | { [key: string]: SyncValue };
-
-export type InitSource =
-  | string
-  | URL
-  | ArrayBuffer
-  | Uint8Array
-  | WebAssembly.Module;
-
-/** Rust errors thrown by synchronization and value conversion. */
-export interface DoxsyncError extends Error {
-  kind: "Internal" | "InvalidData" | "UnexpectedType";
-}
-
+import { InitSource } from './types.js';
+export type { SyncValue, InitSource, DoxsyncError } from './types.js';
+export { Decimal } from 'decimal.js';
+export { Producer, Consumer, supportedProtocols } from './runtime.js';
 /**
- * Initialize once before constructing Producer or Consumer.
+ * Initialize once before constructing Producer or Consumer or calling supportedProtocols.
  * Defaults to the packaged WASM. Concurrent calls share the first call's source
  * and promise; failures can be retried. Later successful calls are no-ops.
  * Strings are URLs, not filesystem paths; Node also accepts file: URLs.
  */
-export function init(source?: InitSource): Promise<void>;
-
-export class Producer {
-  #private;
-  /**
-   * Copies the value into WASM and selects the highest common protocol version.
-   * protocols lists the consumer's supported versions as u32 integers.
-   * Currently only 1 is supported. Missing, invalid, empty, or incompatible
-   * lists throw InvalidData errors. Order and duplicates do not matter.
-   */
-  constructor(value: SyncValue, protocols: readonly number[]);
-  /** Replaces the document after validating and copying the entire value. */
-  replace(value: SyncValue): void;
-  /**
-   * Returns a snapshot with protocol metadata on the first call, then changes.
-   * Returns undefined if unchanged. Retain each message until delivered in order.
-   */
-  produceDiff(): Uint8Array | undefined;
-  /** Release WASM resources. Safe to call repeatedly. */
-  free(): void;
-}
-
-export class Consumer {
-  #private;
-  constructor();
-  /**
-   * Applies one complete message. The first message must declare protocol 1.
-   * Failures leave the document, pools, and protocol state intact.
-   */
-  consumeDiff(bytes: Uint8Array): void;
-  /** Returns an independent copy, or undefined before the first snapshot. */
-  document(): SyncValue | undefined;
-  /** Release WASM resources. Safe to call repeatedly. */
-  free(): void;
-}
+export declare function init(source?: InitSource): Promise<void>;

package/dist/index.js

@@ -1,9 +1,12 @@
-import { initialize } from "./runtime.js";
-
-export { Producer, Consumer } from "./runtime.js";
-
-export function init(source) {
-  return initialize(() => source === undefined
-    ? new URL("./wasm/doxsync_bg.wasm", import.meta.url)
-    : source);
+import { i as e, n as t, r as n, t as r } from "./runtime-BePF61JJ.js";
+import { Decimal as i } from "decimal.js";
+//#region src/index.ts
+function a(e) {
+	return n(() => e === void 0 ? new URL(
+		/* @vite-ignore */
+		"./wasm/doxsync_bg.wasm",
+		import.meta.url
+	) : e);
 }
+//#endregion
+export { r as Consumer, i as Decimal, t as Producer, a as init, e as supportedProtocols };

package/dist/node.d.ts

@@ -0,0 +1,11 @@
+import { InitSource } from './types.js';
+export type { SyncValue, InitSource, DoxsyncError } from './types.js';
+export { Decimal } from 'decimal.js';
+export { Producer, Consumer, supportedProtocols } from './runtime.js';
+/**
+ * Initialize once before constructing Producer or Consumer or calling supportedProtocols.
+ * Defaults to the packaged WASM. Concurrent calls share the first call's source
+ * and promise; failures can be retried. Later successful calls are no-ops.
+ * Strings are URLs, not filesystem paths; Node also accepts file: URLs.
+ */
+export declare function init(source?: InitSource): Promise<void>;

package/dist/node.js

@@ -1,19 +1,13 @@
-import { readFile } from "node:fs/promises";
-import { initialize } from "./runtime.js";
-
-export { Producer, Consumer } from "./runtime.js";
-
-export function init(source) {
-  return initialize(() => {
-    if (source === undefined) {
-      return readFile(new URL("./wasm/doxsync_bg.wasm", import.meta.url));
-    }
-    if (source instanceof URL && source.protocol === "file:") {
-      return readFile(source);
-    }
-    if (typeof source === "string" && source.startsWith("file:")) {
-      return readFile(new URL(source));
-    }
-    return source;
-  });
+import { i as e, n as t, r as n, t as r } from "./runtime-BePF61JJ.js";
+import { Decimal as i } from "decimal.js";
+import { readFile as a } from "node:fs/promises";
+//#region src/node.ts
+function o(e) {
+	return n(() => e === void 0 ? a(new URL(
+		/* @vite-ignore */
+		"./wasm/doxsync_bg.wasm",
+		import.meta.url
+	)) : e instanceof URL && e.protocol === "file:" ? a(e) : typeof e == "string" && e.startsWith("file:") ? a(new URL(e)) : e);
 }
+//#endregion
+export { r as Consumer, i as Decimal, t as Producer, o as init, e as supportedProtocols };

package/dist/runtime-BePF61JJ.js

@@ -0,0 +1,72 @@
+import { Decimal as e } from "decimal.js";
+import t, { Consumer as n, Producer as r, supportedProtocols as i } from "./wasm/doxsync.js";
+//#region src/decimal.ts
+var a = e.clone({
+	precision: 29,
+	minE: -100,
+	maxE: 100
+});
+function o(t) {
+	if (e.isDecimal(t)) {
+		if (!t.isFinite() || t.decimalPlaces() > 28 || t.e > 28) throw Object.assign(/* @__PURE__ */ Error("Decimal outside the supported coefficient or scale range"), { kind: "InvalidData" });
+		return t.toFixed();
+	}
+}
+function s(e) {
+	return new a(e);
+}
+//#endregion
+//#region src/runtime.ts
+var c, l = !1;
+function u(e) {
+	return c ||= Promise.resolve().then(e).then((e) => t({ module_or_path: e })).then(() => {
+		l = !0;
+	}).catch((e) => {
+		throw c = void 0, e;
+	}), c;
+}
+function d() {
+	if (!l) throw Error("Call and await init() before using the doxsync API");
+}
+function f() {
+	return d(), i();
+}
+var p = class {
+	#e;
+	constructor(e, t) {
+		d(), this.#e = new r(e, t, o);
+	}
+	#t() {
+		if (!this.#e) throw Error("Producer has been freed");
+		return this.#e;
+	}
+	replace(e) {
+		this.#t().replace(e);
+	}
+	produceDiff() {
+		return this.#t().produceDiff();
+	}
+	free() {
+		this.#e &&= (this.#e.free(), void 0);
+	}
+}, m = class {
+	#e;
+	constructor() {
+		d(), this.#e = new n();
+	}
+	#t() {
+		if (!this.#e) throw Error("Consumer has been freed");
+		return this.#e;
+	}
+	consumeDiff(e) {
+		this.#t().consumeDiff(e);
+	}
+	document() {
+		return this.#t().document(s);
+	}
+	free() {
+		this.#e &&= (this.#e.free(), void 0);
+	}
+};
+//#endregion
+export { f as i, p as n, u as r, m as t };

package/dist/runtime.d.ts

@@ -0,0 +1,44 @@
+import { InitSource, SyncValue } from './types.js';
+export declare function initialize(loadSource: () => InitSource | Promise<InitSource>): Promise<void>;
+/**
+ * Returns all protocol versions supported by this build, currently [1, 2].
+ * Requires await init(). Each call returns an independent ordinary array.
+ * Consumers can advertise this list to producers for protocol negotiation.
+ */
+export declare function supportedProtocols(): number[];
+export declare class Producer {
+    #private;
+    /**
+     * Copies the value into WASM and selects the highest common protocol version.
+     * protocols lists the consumer's supported versions as u32 integers.
+     * Versions 1 and 2 are supported. Missing, invalid, empty, or incompatible
+     * lists throw InvalidData errors. Order and duplicates do not matter.
+     * Protocol 1 transmits Decimal values as strings; protocol 2 preserves the type.
+     * Protocol 2 also pools binary values; both peers must support that extension.
+     */
+    constructor(value: SyncValue, protocols: readonly number[]);
+    /** Replaces the document after validating and copying the entire value. */
+    replace(value: SyncValue): void;
+    /**
+     * Returns a snapshot with protocol metadata on the first call, then changes.
+     * Returns undefined if unchanged. Retain each message until delivered in order.
+     */
+    produceDiff(): Uint8Array | undefined;
+    /** Release WASM resources. Safe to call repeatedly. */
+    free(): void;
+}
+export declare class Consumer {
+    #private;
+    constructor();
+    /**
+     * Applies one complete message. The first message must declare protocol 1 or 2.
+     * Failures leave the document, pools, and protocol state intact.
+     */
+    consumeDiff(bytes: Uint8Array): void;
+    /** Returns an independent copy, or undefined before the first snapshot.
+     * Protocol 2 decimals become decimal.js instances; their original scale is lost.
+     */
+    document(): SyncValue | undefined;
+    /** Release WASM resources. Safe to call repeatedly. */
+    free(): void;
+}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+import { Decimal } from 'decimal.js';
+/** Numbers are floats; bigint values are integers in [-2^64, 2^64 - 1].
+ * Decimal instances preserve numeric value, but not trailing zeros.
+ */
+export type SyncValue = null | boolean | string | number | bigint | Decimal | Uint8Array | SyncValue[] | {
+    [key: string]: SyncValue;
+};
+export type InitSource = string | URL | ArrayBuffer | Uint8Array | WebAssembly.Module;
+/** Rust errors thrown by synchronization and value conversion. */
+export interface DoxsyncError extends Error {
+    kind: "Internal" | "InvalidData" | "UnexpectedType";
+}

package/dist/wasm/doxsync.d.ts

@@ -5,18 +5,20 @@ export class Consumer {
     free(): void;
     [Symbol.dispose](): void;
     consumeDiff(bytes: any): void;
-    document(): any;
+    document(decimal_from_string: Function): any;
     constructor();
 }
 
 export class Producer {
     free(): void;
     [Symbol.dispose](): void;
-    constructor(value: any, protocols: any);
+    constructor(value: any, protocols: any, decimal_to_string: Function);
     produceDiff(): any;
     replace(value: any): void;
 }
 
+export function supportedProtocols(): Array<any>;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
@@ -24,11 +26,12 @@ export interface InitOutput {
     readonly __wbg_consumer_free: (a: number, b: number) => void;
     readonly __wbg_producer_free: (a: number, b: number) => void;
     readonly consumer_consumeDiff: (a: number, b: any) => [number, number];
-    readonly consumer_document: (a: number) => [number, number, number];
+    readonly consumer_document: (a: number, b: any) => [number, number, number];
     readonly consumer_new: () => number;
-    readonly producer_new: (a: any, b: any) => [number, number, number];
+    readonly producer_new: (a: any, b: any, c: any) => [number, number, number];
     readonly producer_produceDiff: (a: number) => [number, number, number];
     readonly producer_replace: (a: number, b: any) => [number, number];
+    readonly supportedProtocols: () => any;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_exn_store: (a: number) => void;

package/dist/wasm/doxsync.js

@@ -21,10 +21,11 @@ export class Consumer {
         }
     }
     /**
+     * @param {Function} decimal_from_string
      * @returns {any}
      */
-    document() {
-        const ret = wasm.consumer_document(this.__wbg_ptr);
+    document(decimal_from_string) {
+        const ret = wasm.consumer_document(this.__wbg_ptr, decimal_from_string);
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
@@ -53,9 +54,10 @@ export class Producer {
     /**
      * @param {any} value
      * @param {any} protocols
+     * @param {Function} decimal_to_string
      */
-    constructor(value, protocols) {
-        const ret = wasm.producer_new(value, protocols);
+    constructor(value, protocols, decimal_to_string) {
+        const ret = wasm.producer_new(value, protocols, decimal_to_string);
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
@@ -84,6 +86,14 @@ export class Producer {
     }
 }
 if (Symbol.dispose) Producer.prototype[Symbol.dispose] = Producer.prototype.free;
+
+/**
+ * @returns {Array<any>}
+ */
+export function supportedProtocols() {
+    const ret = wasm.supportedProtocols();
+    return ret;
+}
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
@@ -148,6 +158,10 @@ function __wbg_get_imports() {
             const ret = arg0.add(arg1);
             return ret;
         },
+        __wbg_call_6bcf8d3e20937e46: function() { return handleError(function (arg0, arg1, arg2) {
+            const ret = arg0.call(arg1, arg2);
+            return ret;
+        }, arguments); },
         __wbg_charCodeAt_90635349fbda9f5f: function(arg0, arg1) {
             const ret = arg0.charCodeAt(arg1 >>> 0);
             return ret;

package/dist/wasm/doxsync_bg.wasm.d.ts

@@ -4,11 +4,12 @@ export const memory: WebAssembly.Memory;
 export const __wbg_consumer_free: (a: number, b: number) => void;
 export const __wbg_producer_free: (a: number, b: number) => void;
 export const consumer_consumeDiff: (a: number, b: any) => [number, number];
-export const consumer_document: (a: number) => [number, number, number];
+export const consumer_document: (a: number, b: any) => [number, number, number];
 export const consumer_new: () => number;
-export const producer_new: (a: any, b: any) => [number, number, number];
+export const producer_new: (a: any, b: any, c: any) => [number, number, number];
 export const producer_produceDiff: (a: number) => [number, number, number];
 export const producer_replace: (a: number, b: any) => [number, number];
+export const supportedProtocols: () => any;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_exn_store: (a: number) => void;

package/examples/browser.html

@@ -5,6 +5,9 @@
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>doxsync · Sync playground</title>
     <link rel="stylesheet" href="./browser.css">
+    <script type="importmap">
+      { "imports": { "decimal.js": "../node_modules/decimal.js/decimal.mjs" } }
+    </script>
     <script type="module" src="./browser.js"></script>
   </head>
   <body>

package/examples/browser.js

@@ -11,6 +11,7 @@ let loading = false;
 const initialDocument = () => ({
   title: "doxsync playground",
   visitors: 12n,
+  price: new bindings.Decimal("12.34"),
   online: true,
   settings: { theme: "light", volume: 60 },
   tags: ["rust", "wasm"],
@@ -28,6 +29,7 @@ const delayValue = () => {
 // suffix preserves bigint's type instead of presenting it as a JSON string.
 function format(value, depth = 0) {
   if (typeof value === "bigint") return `${value}n`;
+  if (bindings.Decimal.isDecimal(value)) return `Decimal("${value.toFixed()}")`;
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   const array = Array.isArray(value);
   const entries = array ? value : Object.keys(value).sort();
@@ -219,6 +221,7 @@ function send(summary) {
 }
 
 const mutations = [
+  (doc) => { doc.price = doc.price.plus("0.01"); return `price → ${doc.price.toFixed(2)}`; },
   (doc) => { const delta = BigInt(number(1, 5)); doc.visitors += delta; return `visitors increased by ${delta}`; },
   (doc) => { doc.online = !doc.online; return `online → ${doc.online}`; },
   (doc) => { doc.settings.theme = pick(["light", "dark", "system"].filter((value) => value !== doc.settings.theme)); return `settings.theme → ${doc.settings.theme}`; },
@@ -246,7 +249,13 @@ function mutate() {
   try {
     // Producer owns a copy. Keep this display model in step with successfully
     // accepted replacements; no JS implementation of the diff algorithm.
-    const next = structuredClone(state.document);
+    // Copy this demo's containers explicitly: structuredClone cannot copy Decimal.
+    const next = {
+      ...state.document,
+      settings: { ...state.document.settings },
+      tags: [...state.document.tags],
+      price: new bindings.Decimal(state.document.price),
+    };
     const summary = pick(mutations)(next);
     state.producer.replace(next);
     state.document = next;
@@ -293,7 +302,7 @@ function reset() {
   dispose();
   const document = initialDocument();
   state = {
-    document, producer: new bindings.Producer(document, [1]), consumer: new bindings.Consumer(),
+    document, producer: new bindings.Producer(document, bindings.supportedProtocols()), consumer: new bindings.Consumer(),
     producerText: format(document), consumerText: "", queue: [], history: [],
     selected: undefined, sent: 0, totalBytes: 0, unchanged: 0,
     running: true, failed: false,

package/examples/node.mjs

@@ -1,17 +1,18 @@
-import { init, Producer, Consumer } from "@doxsync/core";
+import { init, Producer, Consumer, Decimal, supportedProtocols } from "@doxsync/core";
 
 await init();
-const producer = new Producer({ count: 1n, data: new Uint8Array([1, 2, 3]) }, [1]);
+const producer = new Producer({ count: 1n, price: new Decimal("12.34"), data: new Uint8Array([1, 2, 3]) }, supportedProtocols());
 const consumer = new Consumer();
 
 try {
   consumer.consumeDiff(producer.produceDiff());
   console.log("Snapshot:", consumer.document());
 
-  producer.replace({ count: 2n, data: new Uint8Array([1, 2, 3]) });
+  producer.replace({ count: 2n, price: new Decimal("12.35"), data: new Uint8Array([1, 2, 3]) });
   const message = producer.produceDiff();
   if (message !== undefined) consumer.consumeDiff(message);
   console.log("Updated:", consumer.document());
+  console.log("Exact price:", consumer.document().price.toFixed(2));
   console.log("Unchanged:", producer.produceDiff());
 } finally {
   producer.free();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doxsync/core",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "JavaScript bindings for the doxsync Rust synchronization engine",
   "type": "module",
   "engines": {
@@ -23,7 +23,7 @@
     "LICENSE-APACHE"
   ],
   "scripts": {
-    "build": "node scripts/build.mjs",
+    "build": "node scripts/build-wasm.mjs && vite build",
     "prepack": "npm run build"
   },
   "license": "MIT OR Apache-2.0",
@@ -31,5 +31,14 @@
     "type": "git",
     "url": "git+https://github.com/PeterlitsZo/doxsync.git",
     "directory": "doxsync-js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.0",
+    "vite-plugin-dts": "^5.1.1"
+  },
+  "dependencies": {
+    "decimal.js": "^10.6.0"
   }
 }

package/dist/runtime.js

@@ -1,85 +0,0 @@
-import initWasm, {
-  Producer as WasmProducer,
-  Consumer as WasmConsumer,
-} from "./wasm/doxsync.js";
-
-let initialization;
-let initialized = false;
-
-export function initialize(loadSource) {
-  if (!initialization) {
-    initialization = Promise.resolve()
-      .then(loadSource)
-      .then((source) => initWasm({ module_or_path: source }))
-      .then(() => { initialized = true; })
-      .catch((error) => {
-        initialization = undefined;
-        throw error;
-      });
-  }
-  return initialization;
-}
-
-function requireInitialized() {
-  if (!initialized) {
-    throw new Error("Call and await init() before creating a doxsync object");
-  }
-}
-
-export class Producer {
-  #handle;
-
-  constructor(value, protocols) {
-    requireInitialized();
-    this.#handle = new WasmProducer(value, protocols);
-  }
-
-  #live() {
-    if (!this.#handle) throw new Error("Producer has been freed");
-    return this.#handle;
-  }
-
-  replace(value) {
-    this.#live().replace(value);
-  }
-
-  produceDiff() {
-    return this.#live().produceDiff();
-  }
-
-  free() {
-    if (this.#handle) {
-      this.#handle.free();
-      this.#handle = undefined;
-    }
-  }
-}
-
-export class Consumer {
-  #handle;
-
-  constructor() {
-    requireInitialized();
-    this.#handle = new WasmConsumer();
-  }
-
-  #live() {
-    if (!this.#handle) throw new Error("Consumer has been freed");
-    return this.#handle;
-  }
-
-  consumeDiff(bytes) {
-    this.#live().consumeDiff(bytes);
-  }
-
-  document() {
-    return this.#live().document();
-  }
-
-  free() {
-    if (this.#handle) {
-      this.#handle.free();
-      this.#handle = undefined;
-    }
-  }
-}