Changelog
Every release of twinstate, newest first. Before 1.0, a release marked breaking raises the minor version and says how to migrate; every other release is a patch.
0.1.0 — breaking
2026-10-16
Twinstate now requires zod 4 and Node 24.
- zod
^4.0.0. zod 3.25'szod/v4entry is no longer supported. Twinstate imports fromzod. - Node
>=24, the current LTS.
Migrating: upgrade to zod 4 (zod's migration guide) and Node 24. Code that imported from zod/v4 for Twinstate can import from zod.
0.0.5
2026-10-16
Fixes from a review of everything shipped so far. Some rules get stricter; no app uses Twinstate yet, so none should need changes.
- zod
^3.25.76 || ^4.0.0: earlier 3.25 releases typedzod/v4differently, and everykind()failed to compile on them. CI now also tests the lowest supported zod. patch()can be declared before its kind's parent. It used to throwCannot access … before initialization, including across circular imports.- A field's value must parse again, because a stored value is re-parsed on every load. A
.transformto another type (z.string().transform(Number)) no longer compiles; a trimming one still does. - Mutation arguments are strict at every level. Docs and examples use
z.strictObject. zod's types can't tell strict objects from stripping ones, so a test-time check (argumentProblems, for the test kit'scheckRegistry()) reports anyz.objectorz.looseObjectinside arguments. - A
defaultedkind'sopsare['update']. Its first update writes it, as a single value's does. - A patch can't name a
reffield. The server delivers whatever arefpoints at, so a client setting one could read any embedded record. incompatibleis a built-in rejection reason, likeoutdated, so no mutation may declare it.- Clearer errors: a modifier nested inside another modifier's value now gets the modifier message, not the JSON one.
See Mutations and Values are plain JSON.
0.0.4
2026-10-10
Declare how clients change things and what the server announces: named mutations, patches and events, kept in the registry. Nothing syncs yet; the server comes next.
ts
import { z } from 'zod/v4';
import { event, idOf, mutation, patch, registry } from 'twinstate';
export const twin = registry({
name: 'notes',
kinds: [settings, note, noteBody, image],
mutations: {
updateNoteBody: patch(noteBody, { fields: ['text', 'related'] }),
createNote: mutation(z.object({ id: idOf(note), title: z.string() }), {
effect: (draft, a) => {
draft.create(note, a.id, { title: a.title, updatedAt: '', pinned: false });
},
rejects: ['duplicate'],
}),
},
events: { notice: event(z.object({ text: z.string() })) },
});mutation(args, { effect, rejects }):argsis az.objectof plain JSON.
effectgets a typed draft:create,updateandremove, each allowed only where the kind'sopsinclude it. The draft takes the right id for each kind and shows only the fields clients see.- An effect returns nothing, so an
asyncone doesn't compile, and neither does a recipe that returns a value. rejectslists your own reasons. Declaring a built-in one (invalid,unavailable,error,outdated) doesn't compile.patch(kind, { fields }): lets clients set the named fields of existing records. Its arguments are generated, as{ id, patch }, or just{ patch }for a single value.- It sets only what it's given. Each given field is checked by its own schema. A field left out keeps its value, so no default fills it. A field the patch doesn't name, or an
undefined, is refused. A patch clears a field by sendingnull. - What doesn't compile: naming a
serverOnlyorappendablefield, an unknown field, or no field at all, and patching a kind whoseopslackupdate. Each error says why. event(payload, { maxAge }): a payload of plain JSON. A reconnecting client still receives an event formaxAgemilliseconds, two minutes by default;maxAge: 0never replays it.registry({ mutations, events })keeps them undertwin.mutationsandtwin.events. Patching a kind that isn't in the registry doesn't compile.- Ids are branded on the input side too.
idOf,refandlinktake anId<'note'>, not a string, wherever a value is written. That covers an effect'screate, a mutation's arguments, and ids nested in objects, arrays, tuples and unions. A client mints a new record's id withnewId(note)fromtwinstate/client; it's documented now and built with the client. - "Nothing" is
null. A stored value never holdsundefined: a kind's field is never.optional()or.nullish(), at any depth. Use.nullable().default(null)so a create can leave it out;.default()is still fine. One way to say "nothing" means a patch can clear any field, and records compare the same before and after JSON. The compiler refusesundefined, with a message naming.nullable(), and the test kit's walk finds deeper cases. Mutation arguments and event payloads may still be.optional(). - Migrating: replace
.optional()on a kind's fields with.nullable().default(null), and replacez.partialRecord(…)withz.record(z.string(), …). Both are breaking for 0.0.3 declarations, but no data shipped on 0.0.3. - A kind's fields take no
.catch. It would silently turn a client's bad patch value into the fallback. One in a field doesn't compile, and the test kit's walk finds deeper ones, including inside a.catchall(). The walk is renamed tovalueProblems.
0.0.3
2026-10-10
Declare the registry: every kind in one list, checked as a whole. Relations between kinds come with it, as ref and link. Nothing syncs yet; mutations and events come next.
ts
import { z } from 'zod/v4';
import { kind, link, ref, registry } from 'twinstate';
export const noteBody = kind('noteBody', {
text: z.string(),
images: ref('image').array(), // embedded records, delivered with the body
related: link('note').nullable(), // another root: an Id<'note'>, or null
}, { id: () => note, load: 'lazy', ops: ['create', 'update'] });
export const twin = registry({ name: 'notes', kinds: [settings, note, noteBody, image] });
twin.kinds.noteBody; // every kind, by nameref(name)andlink(name)hold the target's id. Add.array()for several in order, or.nullable()for none. Arefpoints at an embedded kind, and alinkat a root with its own ids.- Relations name their target, so kinds can point at each other in any order. A folder can link to its parent folder, and two kinds can link to each other.
registry()checks every kind at once, at compile time. Each mistake gets one message, naming the kind and the field:- a relation to a missing kind, or to a kind of the wrong sort;
- two kinds with one name;
- a parent left out of the registry;
- a child's
byholding another kind's id; - an embedded kind nothing refs.
- A misspelled option no longer compiles (
validator,query.filters). - Relations stay out of orders and
by. Arefor alinkcan't be a window's order or a child'sby, and arefcan't be a filter. Like the modifiers, relations go only on a kind's own fields.
See Relations and the graph rules.
0.0.2
2026-10-10
The first release with code: declare your data with kind(). Nothing syncs yet; the registry, mutations and the server come next.
ts
import { z } from 'zod/v4';
import { appendable, idOf, invalid, kind, memoryOnly, serverOnly } from 'twinstate';
export const reply = kind('reply', {
status: z.enum(['streaming', 'done']).default('streaming'),
token: serverOnly(z.string().min(1)), // never sent to clients
busy: memoryOnly(z.boolean().default(false)), // back to its default on restart
text: memoryOnly(z.string().default('')).appendable(), // grows: travels as its suffix
}, { id: true, load: 'lazy', ops: ['create', 'update'] });- A kind is a map of fields. Each field is a zod schema, or one wrapped in
serverOnly,memoryOnlyorappendable. - The modifiers start a chain. Each offers the others once, and only where they apply:
memoryOnlyneeds a default,appendableneeds open-ended text, andserverOnlyandappendableexclude each other. - Modifiers go on a kind's own fields. One inside a
z.objectorz.arraydoesn't compile. - The options:
- addressing: a single value, records with their own ids, or one per parent (
id: () => parent, optionallydefaulted); - how it reaches clients, exactly one of:
load,belongsToa lazy root, orembedded;ops, required;
- optionally:
validatewithinvalid(),querywindows, andmemoryOnlykinds.
A window's order, its filters and a child's by can only name fields clients see.
- Branded ids:
Id<'note'>never mixes with another kind's id.idOf(kind)validates a client-chosen id: lowercase letters, digits,-and_in.-separated segments, at most 200 characters, never a Windows-reserved name, so an id is always safe as a file name. - Mistakes fail to compile:
opsmissing, two ways to reach clients, a single value that can be created, a field namedid, aDatein a field, an order naming an unknown or server-only field, and more. See Kinds. - The package ships its docs (
node_modules/twinstate/docs) and its changelog.