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

package/README.md

@@ -6,18 +6,19 @@ 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/`. There are no npm runtime dependencies. 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 +38,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,7 +78,8 @@ 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.
@@ -151,12 +153,24 @@ try {
 }
 ```
 
-The JS package exposes only `init`, `Producer`, and `Consumer` at runtime.
+The JS package exposes `init`, `supportedProtocols`, `Producer`, and `Consumer`
+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.
 
 ### Protocol negotiation
 
+Call `supportedProtocols()` after `await init()` to get all protocol versions
+supported by the local build, currently `[1]`. 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;

package/dist/index.d.ts

@@ -1,64 +1,10 @@
-/** 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 { 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,11 @@
-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-CJqt5vND.js";
+//#region src/index.ts
+function i(e) {
+	return n(() => e === void 0 ? new URL(
+		/* @vite-ignore */
+		"./wasm/doxsync_bg.wasm",
+		import.meta.url
+	) : e);
 }
+//#endregion
+export { r as Consumer, t as Producer, i as init, e as supportedProtocols };

package/dist/node.d.ts

@@ -0,0 +1,10 @@
+import { InitSource } from './types.js';
+export type { SyncValue, InitSource, DoxsyncError } from './types.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,12 @@
-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-CJqt5vND.js";
+import { readFile as i } from "node:fs/promises";
+//#region src/node.ts
+function a(e) {
+	return n(() => e === void 0 ? i(new URL(
+		/* @vite-ignore */
+		"./wasm/doxsync_bg.wasm",
+		import.meta.url
+	)) : e instanceof URL && e.protocol === "file:" ? i(e) : typeof e == "string" && e.startsWith("file:") ? i(new URL(e)) : e);
 }
+//#endregion
+export { r as Consumer, t as Producer, a as init, e as supportedProtocols };

package/dist/runtime-CJqt5vND.js

@@ -0,0 +1,55 @@
+import e, { Consumer as t, Producer as n, supportedProtocols as r } from "./wasm/doxsync.js";
+//#region src/runtime.ts
+var i, a = !1;
+function o(t) {
+	return i ||= Promise.resolve().then(t).then((t) => e({ module_or_path: t })).then(() => {
+		a = !0;
+	}).catch((e) => {
+		throw i = void 0, e;
+	}), i;
+}
+function s() {
+	if (!a) throw Error("Call and await init() before using the doxsync API");
+}
+function c() {
+	return s(), r();
+}
+var l = class {
+	#e;
+	constructor(e, t) {
+		s(), this.#e = new n(e, t);
+	}
+	#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);
+	}
+}, u = class {
+	#e;
+	constructor() {
+		s(), this.#e = new t();
+	}
+	#t() {
+		if (!this.#e) throw Error("Consumer has been freed");
+		return this.#e;
+	}
+	consumeDiff(e) {
+		this.#t().consumeDiff(e);
+	}
+	document() {
+		return this.#t().document();
+	}
+	free() {
+		this.#e &&= (this.#e.free(), void 0);
+	}
+};
+//#endregion
+export { c as i, l as n, o as r, u as t };

package/dist/runtime.d.ts

@@ -0,0 +1,40 @@
+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].
+ * 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.
+     * 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 declare 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;
+}

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+/** 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";
+}

package/dist/wasm/doxsync.d.ts

@@ -17,6 +17,8 @@ export class Producer {
     replace(value: any): void;
 }
 
+export function supportedProtocols(): Array<any>;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
@@ -29,6 +31,7 @@ export interface InitOutput {
     readonly producer_new: (a: any, b: 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

@@ -84,6 +84,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,

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

@@ -9,6 +9,7 @@ export const consumer_new: () => number;
 export const producer_new: (a: any, b: 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.js

@@ -293,7 +293,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,7 +1,7 @@
-import { init, Producer, Consumer } from "@doxsync/core";
+import { init, Producer, Consumer, 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, data: new Uint8Array([1, 2, 3]) }, supportedProtocols());
 const consumer = new Consumer();
 
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doxsync/core",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "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,11 @@
     "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"
   }
 }

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;
-    }
-  }
-}