y-utility

library0.1.4jsnpmunverified

y-utility provides essential helper functionalities for Yjs, a CRDT implementation for collaborative applications. The current stable version is 0.1.4, with releases occurring periodically to address bugs and integrate with newer Yjs versions. Key features include `YMultiDocUndoManager`, which extends Yjs's built-in `UndoManager` to handle undo/redo operations across multiple `Y.Doc` instances, essential for managing complex, nested document structures. It also offers `YKeyValue`, an optimized key-value store designed to address performance inefficiencies and document size growth observed when using `Y.Map` for frequently updated, alternating key-value pairs, thereby reducing metadata overhead and improving encoding size. This library targets environments running Node.js version 16 or newer, aligning with modern JavaScript module standards.

database

npm install y-utility

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · Y-UTILITY

y-utility

databasejavascriptv0.1.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

YMultiDocUndoManager

✓ import { YMultiDocUndoManager } from 'y-utility/y-multidoc-undomanager'

✗ import { YMultiDocUndoManager } from 'y-utility'

This utility is exported from a subpath. Attempting to import directly from the main package path will fail. This package targets ESM primarily, though CJS exports are available via 'require' for specific subpaths like './dist/y-multidoc-undomanager.cjs'.

YKeyValue

✓ import { YKeyValue } from 'y-utility/y-keyvalue'

✗ const { YKeyValue } = require('y-utility/y-keyvalue')

This utility is exported from a subpath. While CommonJS `require` is technically supported for `./dist/y-keyvalue.cjs`, the primary usage pattern for Node.js >=16 is ESM `import`.

* as Y

✓ import * as Y from 'yjs'

✗ import Y from 'yjs'

Yjs itself uses named exports for its core types like `Y.Doc`, `Y.Map`, `Y.Array`. Importing with a namespace `* as Y` is the conventional and correct approach.

Demonstrates how to set up and use `YMultiDocUndoManager` to manage undo/redo history across multiple `Y.Doc` instances and their shared types.

import * as Y from 'yjs'; import { YMultiDocUndoManager } from 'y-utility/y-multidoc-undomanager'; const ydoc1 = new Y.Doc(); const ymap1 = ydoc1.getMap('my-map'); const ydoc2 = new Y.Doc(); const yarray2 = ydoc2.getArray('my-array'); // Changed from ydoc1 to ydoc2 to correctly show multi-doc // Create a multi-document undo manager tracking ymap1 initially const um = new YMultiDocUndoManager([ymap1]); // Add yarray2 to the scope dynamically um.addToScope([yarray2]); // Perform some operations on both documents ymap1.set('a', 1); yarray2.insert(0, ['hello']); ymap1.set('b', 2); console.log('Initial state:'); console.log('ymap1:', ymap1.toJSON()); console.log('yarray2:', yarray2.toArray()); // Undo the last operation (ymap1.set('b', 2)) um.undo(); console.log('\nAfter first undo:'); console.log('ymap1:', ymap1.toJSON()); // { a: 1 } console.log('yarray2:', yarray2.toArray()); // ['hello'] // Undo the next operation (yarray2.insert(0, ['hello'])) um.undo(); console.log('\nAfter second undo:'); console.log('ymap1:', ymap1.toJSON()); // { a: 1 } console.log('yarray2:', yarray2.toArray()); // [] // Undo the first operation (ymap1.set('a', 1)) um.undo(); console.log('\nAfter third undo:'); console.log('ymap1:', ymap1.toJSON()); // {} console.log('yarray2:', yarray2.toArray()); // [] // Redo an operation (ymap1.set('a', 1)) um.redo(); console.log('\nAfter first redo:'); console.log('ymap1:', ymap1.toJSON()); // { a: 1 } console.log('yarray2:', yarray2.toArray()); // []

Debug

Known issues

breakingThe `MultiDocUndoManager` class was renamed to `YMultiDocUndoManager` in version `0.1.2`. Code relying on the old name will break.

fix

Update imports and class instantiations from `MultiDocUndoManager` to `YMultiDocUndoManager`.

affects: <0.1.2

gotchaWhen using `YKeyValue` with extremely large collections (e.g., over 1 million objects), performance may degrade due to frequent calls to `yarray.toArray()`. This is a known limitation acknowledged by the developers, pending future Yjs optimizations.

fix

For datasets approaching or exceeding 1 million objects, monitor performance closely. Consider alternative data structures or custom optimizations if `YKeyValue` becomes a bottleneck. The core Yjs team is exploring future solutions.

affects: >=0.1.0

gotchaWhile `Y.Map` is a general-purpose map, it is inefficient for key-value stores with frequently alternating key updates and deletions. This can lead to significantly larger document sizes due to Yjs's conflict resolution mechanism retaining historical key values. `YKeyValue` from this library specifically addresses this.

fix

For dynamic key-value scenarios with frequent updates and deletions, use `YKeyValue` instead of `Y.Map` to benefit from optimized document size and performance.

affects: >=0.1.0

breakingIn `yjs` v13.6.13, changes were introduced that break `YMultiDocUndoManager`, causing it to undo the entire stack instead of a single item. This affects `y-utility` users depending on this specific `yjs` version.

fix

Downgrade your `yjs` dependency to a version prior to 13.6.13, or check for updates to `y-utility` that explicitly address compatibility with `yjs` 13.6.13 and newer.

affects: yjs@~13.6.13

gotchaThe default `Y.UndoManager` (and by extension, `YMultiDocUndoManager`) disables garbage collection for items on its undo/redo stacks. If undo/redo operations are frequently alternated or stacks are not explicitly managed, this can lead to unbounded document size growth, even with otherwise efficient Yjs operations.

fix

Implement custom logic to manage the `undoStack` and `redoStack` properties of the undo manager, such as splicing them to limit their size, especially when items are popped off the stack, to allow underlying Yjs items to be garbage collected.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: YMultiDocUndoManager is not a constructor

Attempting to import `YMultiDocUndoManager` incorrectly, such as from the main 'y-utility' package instead of its specific subpath.

fix

Ensure you are importing from the correct subpath: `import { YMultiDocUndoManager } from 'y-utility/y-multidoc-undomanager'`.

Error: Cannot find module 'y-utility/y-keyvalue'

The module resolver cannot find the specified subpath. This can happen if using CommonJS `require()` without a compatible `exports` map, or an outdated bundler.

fix

For modern Node.js environments (>=16), use ESM `import`. If using CommonJS, check your bundler configuration or consider using the explicit CommonJS export path if available (e.g., `require('y-utility/dist/y-keyvalue.cjs')`).

Error: Peer dependency 'yjs@^13.5.29' not installed or incompatible.

The `yjs` package, a required peer dependency, is either missing from your project's `node_modules` or its installed version does not satisfy the `y-utility`'s required version range.

fix

Install `yjs` with `npm install yjs@^13.5.29` or ensure your existing `yjs` version is within the compatible range.

Upgrade

Version history

0.1.4latest on npm

Audit

Dependencies

yjsrequiredPeer dependency for core Yjs functionality. This library extends and optimizes features of Yjs.

Agent activity

25 hits · last 30 days

node