workspace-api_skill

Overview

This skill provides TypeScript-first workspace API patterns for defineTable, defineKv, versioning, and migrations. It enforces type-safe schemas, branded IDs, and clear migration rules so schemas evolve safely over time. Use it to declare tables or KV stores, add versions, and author migrations that always produce the latest shape.

How this skill works

You declare schemas with defineTable() or defineKv() using arktype definitions, either as a single-version shorthand or a builder that chains .version() and .migrate(). Tables require a numeric _v discriminant; KV stores may omit _v or use it as an explicit discriminant. Migrations receive a union of prior versions and must return the latest version output, using switch(row._v) for discrimination.

When to use it

• Defining a new table or KV store schema.
• Adding a new schema version for tables or KV stores.
• Writing migrations that transform older rows to the latest version.
• Converting shorthand single-version schemas into builder-style multiple versions.
• Enforcing branded ID types for table primary keys and foreign keys.

Best practices

• Always include _v (number literal) for tables; arktype enforces this at compile time.
• Brand every table id and every string foreign key with a unique branded type to prevent ID mixups.
• Migrate directly to the latest version in one function; do not chain incremental migrations through intermediate versions.
• Co-locate branded type + arktype pipe with the workspace definition file for clarity and safety.
• For optional foreign keys use .or('undefined') in the schema; for generated IDs cast via string to the branded type when creating values.

Example use cases

• Create a users table with a single-version shorthand schema including id and _v.
• Evolve a posts table: add views in v2 and write a migrate() that sets views for v1 rows.
• Define a KV store for UI theme settings that starts without _v, then add a v2 with fontSize and a migration.
• Implement branded ConversationId and ChatMessageId types so functions accept the correct ID types and avoid mixups.
• Convert a legacy shorthand table to the builder pattern to support future schema versions and migrations.