static-workspace-api_skill

Overview

This skill provides a type-safe, versioned API for defining workspace tables and key-value (KV) stores using defineTable and defineKv. It enforces schema discriminants, supports multi-version builder patterns, and includes structured migration functions. Use it to manage schema evolution with clear migration rules and compile-time guarantees.

How this skill works

You declare schemas either as a single-version shorthand or with a builder that registers multiple .version(...) entries. Tables must include a numeric _v discriminant; KV stores may omit _v or use it explicitly. A .migrate(fn) handler receives any older version and must return the latest-version shape, with the type system narrowing _v automatically.

When to use it

• Defining a new table or KV store schema for workspace data.
• Adding a new schema version to an existing table or KV store.
• Writing migration functions to transform older rows to the latest version.
• Converting shorthand single-version schemas to the builder pattern for future versions.
• Enforcing compile-time guarantees about schema versions and required fields.

Best practices

• Always include _v (number literal) for tables; KV stores can omit it if you prefer field-presence detection.
• Place _v as the last field in schema objects to follow the convention.
• Write migration functions that switch on row._v and return the latest shape in each case.
• Migrate directly to the latest version in one step — avoid incremental chaining through intermediate versions.
• Rely on TypeScript’s contextual narrowing; you don’t need as const for _v in migration returns.

Example use cases

• Create a users table with a required _v and extend it later with new fields via .version(...) and .migrate(...).
• Define a theme KV store without _v, then add a fontSize field in a later version and migrate existing entries.
• Convert a single-version posts table shorthand into a builder to add views and tags in subsequent versions.
• Implement a migration that transforms v1 rows directly to v3 by handling each discriminant case.
• Use defineKv() for flexible per-user settings where schema changes are optional and field-presence is acceptable.