sveltekit-discriminated-fields 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# sveltekit-discriminated-fields
+
+Type-safe discriminated union support for SvelteKit form fields.
+
+## The Problem
+
+When using SvelteKit's `form()` with discriminated union schemas (e.g., Zod's `z.discriminatedUnion`), the generated `fields` object is a **union of field objects**. TypeScript only allows access to properties that exist on ALL variants - meaning variant-specific fields are completely inaccessible.
+
+Given a typical SvelteKit setup:
+
+```typescript
+// data.remote.ts
+import { z } from "zod";
+import { form } from "$app/server/remote";
+
+const shapeSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("circle"), radius: z.number() }),
+  z.object({
+    kind: z.literal("rectangle"),
+    width: z.number(),
+    height: z.number(),
+  }),
+  z.object({ kind: z.literal("point") }),
+]);
+
+export const shapeForm = form(shapeSchema, async (data) => {
+  // handle form submission
+});
+```
+
+```svelte
+<!-- +page.svelte (without this library) -->
+<script lang="ts">
+  import { shapeForm } from './data.remote.ts';
+
+  const form = shapeForm();
+  const shape = form.fields;
+</script>
+
+<select {...shape.kind.as('select')}>
+  <option value="circle">Circle</option>
+  <option value="rectangle">Rectangle</option>
+  <option value="point">Point</option>
+</select>
+
+{#if shape.kind.value() === 'circle'}
+  <!-- ERROR: Property 'radius' does not exist on type 'ShapeFields' -->
+  <input {...shape.radius.as('number')} />
+{:else if shape.kind.value() === 'rectangle'}
+  <!-- ERROR: Property 'width' does not exist on type 'ShapeFields' -->
+  <input {...shape.width.as('number')} />
+{/if}
+```
+
+The issue: `shape.kind.value() === 'circle'` doesn't narrow the type because method calls don't provide TypeScript control flow analysis. You're stuck - variant-specific fields are inaccessible, and there's no way to narrow to access them.
+
+## The Solution
+
+This library wraps your discriminated union fields to:
+
+1. Make all variant fields accessible
+2. Add a `${key}Value` property that enables TypeScript narrowing
+
+```svelte
+<!-- +page.svelte (with this library) -->
+<script lang="ts">
+  import { shapeForm } from './data.remote.ts';
+  import { discriminatedFields } from 'sveltekit-discriminated-fields';  // +
+
+  const form = shapeForm();
+  const shape = discriminatedFields('kind', form.fields);                 // changed
+</script>
+
+<select {...shape.kind.as('select')}>
+  <option value="circle">Circle</option>
+  <option value="rectangle">Rectangle</option>
+  <option value="point">Point</option>
+</select>
+
+{#if shape.kindValue === 'circle'}<!-- changed -->
+  <input {...shape.radius.as('number')} /><!-- now works! -->
+{:else if shape.kindValue === 'rectangle'}<!-- changed -->
+  <input {...shape.width.as('number')} /><!-- now works! -->
+  <input {...shape.height.as('number')} />
+  <!-- ERROR: Property 'radius' does not exist - correctly rejected -->
+  <input {...shape.radius.as('number')} />
+{/if}
+```
+
+The changes:
+
+1. Import `discriminatedFields` from this library
+2. Wrap `form.fields` with `discriminatedFields('kind', ...)`
+3. Use `shape.kindValue` instead of `shape.kind.value()` for narrowing
+
+## Installation
+
+```bash
+npm install sveltekit-discriminated-fields
+```
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { paymentForm } from './data.remote.ts';
+  import { discriminatedFields } from 'sveltekit-discriminated-fields';
+
+  const form = paymentForm();
+
+  // Wrap fields with $derived for reactivity
+  // The first argument is your discriminator key (e.g., 'type', 'kind', 'channel')
+  const payment = $derived(discriminatedFields('type', form.fields));
+
+  function setCardDefaults() {
+    // set() is type-safe - TypeScript enforces correct fields for each variant
+    payment.set({ type: 'card', cardNumber: '', cvv: '' });
+  }
+</script>
+
+<!-- typeValue is undefined until form is initialized -->
+{#if payment.typeValue === undefined}
+  <p>Loading...</p>
+{:else}
+  <select {...payment.type.as('select')}>
+    <option value="card">Card</option>
+    <option value="bank">Bank Transfer</option>
+  </select>
+
+  <!-- Use typeValue (not type.value()) for type narrowing -->
+  {#if payment.typeValue === 'card'}
+    <input {...payment.cardNumber.as('string')} />
+    <input {...payment.cvv.as('string')} />
+  {:else if payment.typeValue === 'bank'}
+    <input {...payment.accountNumber.as('string')} />
+    <input {...payment.sortCode.as('string')} />
+  {/if}
+{/if}
+```
+
+## API
+
+### `discriminatedFields(key, fields)`
+
+Wraps discriminated union form fields for type-safe narrowing.
+
+**Parameters:**
+
+- `key` - The discriminator key (e.g., `'type'`, `'kind'`, `'channel'`)
+- `fields` - Form fields from a discriminated union schema
+
+**Returns:** A proxy object with:
+
+- All original fields passed through unchanged
+- `${key}Value` - The current discriminator value (for narrowing)
+- `set()` - Type-safe setter that infers variant from discriminator
+
+### `DiscriminatedData<T>`
+
+Type helper that extracts the underlying data type from wrapped fields:
+
+```typescript
+const payment = discriminatedFields('type', form.fields);
+type Payment = DiscriminatedData<typeof payment>;
+// { type: 'card'; cardNumber: string; cvv: string } | { type: 'bank'; accountNumber: string; sortCode: string }
+```
+
+Useful when you need to reference the data type elsewhere, such as defining default values or passing data to other functions.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export type DiscriminatedData<T> = T extends {
+    set: (v: infer D) => unknown;
+} ? D : never;
+type Setter<K extends string, T, D = DiscriminatedData<T>> = {
+    set: <V extends D[K & keyof D]>(data: Extract<D, {
+        [P in K]: V;
+    }>) => void;
+};
+type Keys<T> = T extends unknown ? keyof T : never;
+type KeyValue<K extends string, V> = {
+    [P in `${K}Value`]: V;
+};
+type Fields<T> = {
+    [P in Keys<T>]: T extends Record<P, infer V> ? V : never;
+};
+type Variant<K extends string, T, V> = KeyValue<K, V> & Fields<T>;
+type Narrowed<K extends string, T> = T extends {
+    [P in K]: {
+        value(): infer V;
+    };
+} ? Variant<K, T, V> : never;
+type Union<K extends string, T> = Narrowed<K, T> | Variant<K, T, undefined>;
+type DiscriminatedFields<K extends string, T> = Setter<K, T> & Union<K, T>;
+/**
+ * Wraps discriminated union form fields, adding ${key}Value for type narrowing.
+ * - All original fields pass through unchanged (type, issues, allIssues, etc.)
+ * - `set` is overridden with type-safe version
+ * - `${key}Value` is added for discriminator value (e.g., `reward.typeValue`)
+ *
+ * @param key - Discriminator key (e.g. 'type')
+ * @param fields - Form fields from a discriminated union schema
+ * @returns Passthrough object with type-safe set() and ${key}Value for narrowing
+ */
+export declare function discriminatedFields<K extends string, T extends {
+    set: (v: never) => unknown;
+} & Record<K, {
+    value(): unknown;
+}>>(key: K, fields: T): DiscriminatedFields<K, T>;
+export {};

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * Wraps discriminated union form fields, adding ${key}Value for type narrowing.
+ * - All original fields pass through unchanged (type, issues, allIssues, etc.)
+ * - `set` is overridden with type-safe version
+ * - `${key}Value` is added for discriminator value (e.g., `reward.typeValue`)
+ *
+ * @param key - Discriminator key (e.g. 'type')
+ * @param fields - Form fields from a discriminated union schema
+ * @returns Passthrough object with type-safe set() and ${key}Value for narrowing
+ */
+export function discriminatedFields(key, fields) {
+    const proxy = new Proxy(fields, {
+        get(target, prop) {
+            if (prop === `${key}Value`)
+                return target[key].value();
+            if (prop === 'set')
+                return (data) => target.set(data);
+            return Reflect.get(target, prop);
+        },
+        has(target, prop) {
+            return prop === `${key}Value` || prop in target;
+        }
+    });
+    return proxy;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "sveltekit-discriminated-fields",
+	"version": "0.1.0",
+	"description": "Type-safe discriminated union support for SvelteKit form fields",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"check": "tsc --noEmit",
+		"test:types": "tsc -p test/types/tsconfig.json",
+		"test": "npm run test:types",
+		"prepublishOnly": "npm run test && npm run build"
+	},
+	"keywords": [
+		"svelte",
+		"sveltekit",
+		"forms",
+		"discriminated-union",
+		"typescript"
+	],
+	"author": "robertadamsonsmith",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/robertadamsonsmith/sveltekit-discriminated-fields"
+	},
+	"devDependencies": {
+		"typescript": "^5.0.0"
+	}
+}