@formspec/runtime 0.1.0-alpha.0 → 0.1.0-alpha.4

package/README.md

@@ -0,0 +1,127 @@
+# @formspec/runtime
+
+Runtime helpers for FormSpec - resolvers and data fetching.
+
+## Installation
+
+```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.
+
+## Requirements
+
+This package is ESM-only and requires:
+
+```json
+// package.json
+{
+  "type": "module"
+}
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
+  }
+}
+```
+
+## Usage
+
+### Define Resolvers for Dynamic Enums
+
+```typescript
+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" }),
+);
+
+// Define type-safe resolvers
+const resolvers = defineResolvers(OrderForm, {
+  fetch_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",
+    };
+  },
+});
+
+// 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
+});
+```
+
+## License
+
+UNLICENSED

package/dist/runtime.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `@formspec/runtime` - Runtime helpers for FormSpec
+ *
+ * This package provides utilities for working with FormSpec forms at runtime:
+ * - `defineResolvers()` - Type-safe resolver definitions for dynamic enum fields
+ *
+ * @example
+ * ```typescript
+ * import { defineResolvers } from "@formspec/runtime";
+ * import { formspec, field } from "@formspec/dsl";
+ *
+ * // Define a form with dynamic enum fields
+ * const form = formspec(
+ *   field.dynamicEnum("country", "countries", { label: "Country" }),
+ * );
+ *
+ * // Define resolvers for the form's data sources
+ * const resolvers = defineResolvers(form, {
+ *   countries: async () => ({
+ *     options: [
+ *       { value: "us", label: "United States" },
+ *       { value: "ca", label: "Canada" },
+ *     ],
+ *     validity: "valid",
+ *   }),
+ * });
+ *
+ * // Use the resolver
+ * const result = await resolvers.get("countries")();
+ * console.log(result.options); // [{ value: "us", ... }, { value: "ca", ... }]
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { Conditional } from '@formspec/core';
+import type { DataSourceRegistry } from '@formspec/core';
+import type { DynamicEnumField } from '@formspec/core';
+import type { FetchOptionsResponse } from '@formspec/core';
+import type { FormElement } from '@formspec/core';
+import type { FormSpec } from '@formspec/core';
+import type { Group } from '@formspec/core';
+
+/**
+ * Defines resolvers for a form's dynamic data sources.
+ *
+ * This function provides type-safe resolver definitions that match
+ * the form's dynamic enum fields.
+ *
+ * @example
+ * ```typescript
+ * declare module "@formspec/core" {
+ *   interface DataSourceRegistry {
+ *     countries: { id: string; code: string; name: string };
+ *   }
+ * }
+ *
+ * const form = formspec(
+ *   field.dynamicEnum("country", "countries", { label: "Country" }),
+ * );
+ *
+ * const resolvers = defineResolvers(form, {
+ *   countries: async () => ({
+ *     options: [
+ *       { value: "us", label: "United States", data: { id: "us", code: "US", name: "United States" } },
+ *       { value: "ca", label: "Canada", data: { id: "ca", code: "CA", name: "Canada" } },
+ *     ],
+ *     validity: "valid",
+ *   }),
+ * });
+ *
+ * // Use the resolver
+ * const result = await resolvers.get("countries")();
+ * ```
+ *
+ * @param form - The FormSpec containing dynamic enum fields
+ * @param resolvers - Map of resolver functions for each data source
+ * @returns A ResolverRegistry for type-safe access to resolvers
+ */
+export declare function defineResolvers<E extends readonly FormElement[], Sources extends string = ExtractDynamicSourcesFromArray<E> & string>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources>;
+
+/**
+ * Extracts all dynamic enum source keys from a form's elements.
+ */
+declare type ExtractDynamicSources<E> = E extends DynamicEnumField<string, infer S> ? S : E extends Group<infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : never;
+
+declare type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [
+infer First,
+...infer Rest
+] ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest> : never;
+
+/**
+ * A resolver function that fetches options for a data source.
+ *
+ * @typeParam Source - The data source key from DataSourceRegistry
+ * @typeParam T - The data type for options (from DataSourceRegistry)
+ */
+export declare type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (params?: Record<string, unknown>) => Promise<FetchOptionsResponse<T>>;
+
+/**
+ * Map of resolver functions for a form's dynamic data sources.
+ */
+export declare type ResolverMap<Sources extends string> = {
+    [S in Sources]: S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+};
+
+/**
+ * A resolver registry that provides type-safe access to resolvers.
+ */
+export declare interface ResolverRegistry<Sources extends string> {
+    /**
+     * Gets a resolver by data source name.
+     */
+    get<S extends Sources>(source: S): S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+    /**
+     * Checks if a resolver exists for a data source.
+     */
+    has(source: string): boolean;
+    /**
+     * Gets all registered data source names.
+     */
+    sources(): Sources[];
+}
+
+export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formspec/runtime",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.4",
   "description": "Runtime helpers for FormSpec - resolvers and data fetching",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,14 +12,15 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
-    "@formspec/core": "0.1.0-alpha.0"
+    "@formspec/core": "0.1.0-alpha.4"
   },
   "devDependencies": {
     "vitest": "^3.0.0",
-    "@formspec/dsl": "0.1.0-alpha.0"
+    "@formspec/dsl": "0.1.0-alpha.4"
   },
   "publishConfig": {
     "access": "public"
@@ -27,7 +28,7 @@
   "keywords": [],
   "license": "UNLICENSED",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && api-extractor run --local",
     "clean": "rm -rf dist temp",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",