diffable-objects

library0.1.1jsnpmunverified

A lightweight library for tracking and persisting state changes in Cloudflare Durable Objects using SQLite, version 0.1.1. It simplifies state management by automatically diffing property assignments and storing only mutations, reducing bandwidth and storage costs. Key differentiators from manual state handling include decorator-based or explicit state registration, configurable snapshot policies (e.g., every-change), and tight integration with Cloudflare Workers. The package is in early development with decorator support requiring wrangler@next. Ships TypeScript types and is designed for serverless environments.

database devops

npm install diffable-objects

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DIFFABLE-OBJECTS

diffable-objects

databasejavascriptv0.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

diffable

✓ import { diffable } from 'diffable-objects'

✗ const { diffable } = require('diffable-objects')

Decorator for automatic state tracking; ESM-only, requires wrangler@next for decorator support

state

✓ import { state } from 'diffable-objects'

✗ import state from 'diffable-objects'

Function to register a property for explicit state tracking; named export, not default

DurableObject

✓ import { DurableObject } from 'cloudflare:workers'

✗ import { DurableObject } from 'diffable-objects'

DurableObject base class is from the Cloudflare workers runtime, not from this package

Demonstrates explicit state tracking with `state()`: creates a Durable Object with a tracked state object, mutates it, and retrieves it.

import { DurableObject } from 'cloudflare:workers'; import { state } from 'diffable-objects'; export class MyObject extends DurableObject { #myState = state(this.ctx, 'myState', { count: 0, items: [] }); increment() { this.#myState.count++; } addItem(item: string) { this.#myState.items.push(item); } getState() { return this.#myState; } }

Debug

Known issues

breakingDecorator support requires wrangler@next and is experimental

fix

Use explicit `state()` function instead of `@diffable` decorator until wrangler@next is stable

affects: >=0.1.0

gotchaState mutations must be done on the tracked object itself, not on a copy

fix

Always mutate `this.#state` directly; do not extract to a local variable and modify it

affects: >=0.1.0

deprecatedSnapshot policy 'every-n-seconds' is deprecated in favor of 'periodic'

fix

Use `snapshotPolicy: 'periodic'` with appropriate options

affects: >=0.1.0

gotchaThe 'state' function requires 'this.ctx' to be the Durable Object's context, not the storage

fix

Pass `this.ctx` (the DurableObjectState) to `state()`

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: diffable is not a function

Decorator not supported or not enabled in the current wrangler version

fix

Use explicit `state()` function instead of `@diffable`, or update wrangler to @next

Error: Cannot find module 'cloudflare:workers'

Running outside of Cloudflare Workers environment

fix

Ensure code runs in a Cloudflare Worker with durable objects enabled

TypeError: Cannot read properties of undefined (reading 'storage')

State not correctly passed or ctx is undefined

fix

Verify that `state()` is called with `this.ctx` and that the Durable Object is properly bound

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

cloudflare:workersrequiredRequired for DurableObject base class and runtime APIs

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/zebp/diffable-objects ↗

packagediffable-objects ↗

homepagehttps://github.com/zebp/diffable-objects#readme ↗