@formspec/runtime 0.1.0-alpha.17 → 0.1.0-alpha.19

package/README.md

@@ -1,125 +1,47 @@
 # @formspec/runtime
 
-Runtime helpers for FormSpec - resolvers and data fetching.
+Runtime helpers for dynamic FormSpec data sources.
 
-## Installation
+## Install
 
 ```bash
-npm install @formspec/runtime
-# or
 pnpm add @formspec/runtime
 ```
 
-> **Note:** Most users should install the `formspec` umbrella package instead, which re-exports everything from this package.
+Or use:
 
-## Requirements
-
-This package is ESM-only and requires:
-
-```json
-// package.json
-{
-  "type": "module"
-}
-```
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext"
-  }
-}
+```bash
+pnpm add formspec
 ```
 
-## Usage
+## Main API
 
-### Define Resolvers for Dynamic Enums
+`defineResolvers(form, resolvers)` creates a typed resolver registry for the dynamic enum sources used by a form.
 
-```typescript
+```ts
+import { field, formspec } from "@formspec/dsl";
 import { defineResolvers } from "@formspec/runtime";
-import { formspec, field } from "@formspec/dsl";
 
-// Define a form with dynamic enum fields
-const OrderForm = formspec(
-  field.dynamicEnum("country", "fetch_countries", { label: "Country" }),
-  field.dynamicEnum("state", "fetch_states", { label: "State" })
+const Form = formspec(
+  field.dynamicEnum("country", "countries"),
+  field.dynamicEnum("state", "states")
 );
 
-// Define type-safe resolvers
-const resolvers = defineResolvers(OrderForm, {
-  fetch_countries: async () => ({
+const resolvers = defineResolvers(Form, {
+  countries: async () => ({
     options: [
       { value: "us", label: "United States" },
       { value: "ca", label: "Canada" },
-      { value: "uk", label: "United Kingdom" },
     ],
     validity: "valid",
   }),
-
-  fetch_states: async (params) => {
-    // Params can include any context needed for the lookup (e.g. form data)
-    const response = await fetch(`/api/states?country=${params?.country}`);
-    const states = await response.json();
-    return {
-      options: states.map((s: { code: string; name: string }) => ({
-        value: s.code,
-        label: s.name,
-      })),
-      validity: "valid",
-    };
-  },
+  states: async () => ({
+    options: [],
+    validity: "unknown",
+  }),
 });
 
-// Use the resolver
-const countries = await resolvers.get("fetch_countries")();
-console.log(countries.options);
-// [{ value: "us", label: "United States" }, ...]
-```
-
-### Resolver Response Format
-
-```typescript
-interface FetchOptionsResponse {
-  options: Array<{
-    value: string;
-    label: string;
-  }>;
-  validity: "valid" | "invalid" | "unknown";
-}
-```
-
-## API Reference
-
-### Functions
-
-| Function                           | Description                          |
-| ---------------------------------- | ------------------------------------ |
-| `defineResolvers(form, resolvers)` | Create a type-safe resolver registry |
-
-### Types
-
-| Type                  | Description                           |
-| --------------------- | ------------------------------------- |
-| `Resolver`            | Async function that fetches options   |
-| `ResolverMap<F>`      | Map of data source names to resolvers |
-| `ResolverRegistry<F>` | Registry with `get()` method          |
-
-## Type Safety
-
-The `defineResolvers` function enforces that:
-
-1. All data sources referenced in the form have corresponding resolvers
-2. Resolver names match the data source IDs in the form
-3. Return types match the expected `FetchOptionsResponse` format
-
-```typescript
-// TypeScript error: Missing resolver for "fetch_states"
-const resolvers = defineResolvers(OrderForm, {
-  fetch_countries: async () => ({ ... }),
-  // Error: 'fetch_states' is required
-});
+const countries = await resolvers.get("countries")();
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formspec/runtime",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.19",
   "description": "Runtime helpers for FormSpec - resolvers and data fetching",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -18,11 +18,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@formspec/core": "0.1.0-alpha.17"
+    "@formspec/core": "0.1.0-alpha.19"
   },
   "devDependencies": {
     "vitest": "^3.0.0",
-    "@formspec/dsl": "0.1.0-alpha.17"
+    "@formspec/dsl": "0.1.0-alpha.19"
   },
   "publishConfig": {
     "access": "public"