Skip to content

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's zod/v4 entry is no longer supported. Twinstate imports from zod.
  • 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 typed zod/v4 differently, and every kind() 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 throw Cannot 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 .transform to 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's checkRegistry()) reports any z.object or z.looseObject inside arguments.
  • A defaulted kind's ops are ['update']. Its first update writes it, as a single value's does.
  • A patch can't name a ref field. The server delivers whatever a ref points at, so a client setting one could read any embedded record.
  • incompatible is a built-in rejection reason, like outdated, 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 }):
    • args is a z.object of plain JSON.
  • effect gets a typed draft: create, update and remove, each allowed only where the kind's ops include it. The draft takes the right id for each kind and shows only the fields clients see.
  • An effect returns nothing, so an async one doesn't compile, and neither does a recipe that returns a value.
  • rejects lists 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 sending null.
  • What doesn't compile: naming a serverOnly or appendable field, an unknown field, or no field at all, and patching a kind whose ops lack update. Each error says why.
  • event(payload, { maxAge }): a payload of plain JSON. A reconnecting client still receives an event for maxAge milliseconds, two minutes by default; maxAge: 0 never replays it.
  • registry({ mutations, events }) keeps them under twin.mutations and twin.events. Patching a kind that isn't in the registry doesn't compile.
  • Ids are branded on the input side too. idOf, ref and link take an Id<'note'>, not a string, wherever a value is written. That covers an effect's create, a mutation's arguments, and ids nested in objects, arrays, tuples and unions. A client mints a new record's id with newId(note) from twinstate/client; it's documented now and built with the client.
  • "Nothing" is null. A stored value never holds undefined: 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 refuses undefined, 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 replace z.partialRecord(…) with z.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 to valueProblems.

See Mutations and Events.

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 name
  • ref(name) and link(name) hold the target's id. Add .array() for several in order, or .nullable() for none. A ref points at an embedded kind, and a link at 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 by holding 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. A ref or a link can't be a window's order or a child's by, and a ref can'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, memoryOnly or appendable.
  • The modifiers start a chain. Each offers the others once, and only where they apply: memoryOnly needs a default, appendable needs open-ended text, and serverOnly and appendable exclude each other.
  • Modifiers go on a kind's own fields. One inside a z.object or z.array doesn't compile.
  • The options:
  • addressing: a single value, records with their own ids, or one per parent (id: () => parent, optionally defaulted);
  • how it reaches clients, exactly one of: load, belongsTo a lazy root, or embedded;
    • ops, required;
  • optionally: validate with invalid(), query windows, and memoryOnly kinds.

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: ops missing, two ways to reach clients, a single value that can be created, a field named id, a Date in 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.