@kaliber/forms 2.1.2 → 3.0.0

package/src/snapshot.js

@@ -1,6 +1,13 @@
 import { subscribeToAll, subscribeToChildren } from './state'
+/** @import { State, Expand, Falsy, Field, Snapshot, ValidationError } from './types.ts' */
 
+/**
+ * @template {Field} T
+ * @param {T} field
+ * @returns {Expand<Snapshot.FromField<T>>}
+ */
 export function get(field) {
+  // @ts-expect-error
   return {
     'object': getForObject,
     'array': getForArray,
@@ -8,11 +15,24 @@ export function get(field) {
   }[field.type](field)
 }
 
+/**
+ * @template {Field} T
+ * @arg {T} field
+ * @arg {(snapshot: ReturnType<typeof get<T>>) => void} f
+ * @returns {State.Unsubscribe}
+ */
 export function subscribe(field, f) {
   return subscribeToFieldState(field, x => f(get(x)))
 }
 
+/**
+ * @template {Field} T
+ * @arg {T} field
+ * @arg {(field: T) => void} f
+ * @returns {State.Unsubscribe}
+ */
 export function subscribeToFieldState(field, f) {
+  // @ts-expect-error
   return {
     'object': subscribeForObject,
     'array': subscribeForArray,
@@ -20,6 +40,11 @@ export function subscribeToFieldState(field, f) {
   }[field.type](field, f)
 }
 
+/**
+ * @template {Field.Object} T
+ * @arg {T} field
+ * @returns {Snapshot.FromField<T>}
+ */
 function getForObject(field) {
   const { error, invalid } = field.state.get()
   const { childrenInvalid, childErrors, childValues } =  Object.entries(field.fields).reduce(
@@ -34,13 +59,18 @@ function getForObject(field) {
     { childrenInvalid: false, childErrors: {}, childValues: {} }
   )
 
-  return {
+  return /** @type {Snapshot.FromField<T>} */ ({
     invalid: invalid || childrenInvalid,
     value: childValues,
     error: { self: error, children: childErrors },
-  }
+  })
 }
 
+/**
+ * @template {Field.Array} T
+ * @arg {T} field
+ * @returns {Snapshot.FromField<T>}
+ */
 function getForArray(field) {
   const { children, error, invalid } = field.state.get()
   const { childrenInvalid, childValues, childErrors } = children.reduce(
@@ -54,26 +84,44 @@ function getForArray(field) {
     },
     { childrenInvalid: false, childValues: [], childErrors: [] }
   )
-  return {
+  return /** @type {Snapshot.FromField<T>} */ ({
     invalid: invalid || childrenInvalid,
     value: childValues,
     error: { self: error, children: childErrors },
-  }
+  })
 }
 
+/**
+ * @template {Field.Basic} T
+ * @arg {T} field
+ * @returns {Snapshot.FromField<T>}
+ */
 function getForBasic(field) {
   const { value, error, invalid } = field.state.get()
-  return { value, error, invalid }
+  return /** @type {Snapshot.FromField<T>} */ ({ value, error, invalid })
 }
 
+/**
+ * @template {Field.Object} T
+ * @arg {T} field
+ * @arg {(field: T) => void} f
+ * @returns {State.Unsubscribe}
+ */
 function subscribeForObject(field, f) {
   return subscribeToChildren({
     children: Object.values(field.fields),
+    /** @arg {ReturnType<typeof get<T>>} _ */
     notify: _ => f(field),
     subscribeToChild: subscribe,
   })
 }
 
+/**
+ * @template {Field.Array} T
+ * @arg {T} field
+ * @arg {(field: T) => void} f
+ * @returns {State.Unsubscribe}
+ */
 function subscribeForArray(field, f) {
   return subscribeToAll({
     state: field.state,
@@ -83,6 +131,12 @@ function subscribeForArray(field, f) {
   })
 }
 
+/**
+ * @template {Field.Basic} T
+ * @arg {T} field
+ * @arg {(field: T) => void} f
+ * @returns {State.Unsubscribe}
+ */
 function subscribeForBasic(field, f) {
   return field.state.subscribe(_ => f(field))
 }

package/src/snapshot.type.test.ts

@@ -0,0 +1,135 @@
+import { useForm } from './hooks'
+import { array, object } from './schema'
+import * as snapshot from './snapshot'
+import { asConst } from './type-helpers.js'
+import { expectAssignable, expectNotAny, expectNotNever, Prepared } from './type.test.helpers.ts'
+import { Falsy, ValidationError } from './types.ts'
+import { optionalT, requiredT } from './validation'
+
+const { form } = useForm({
+  fields: {
+    a: optionalT('string'),
+    b: optionalT('number'),
+    c: object({
+      a: optionalT('string'),
+      b: optionalT('number'),
+    }),
+    d: array({
+      a: optionalT('string'),
+      b: optionalT('number'),
+    }),
+    e: array(
+      (initialValue: { type: string }) => {
+        return (
+          initialValue.type === 'a' ? asConst({ type: requiredT('string'), a: optionalT('string') }) :
+          initialValue.type === 'b' ? asConst({ type: requiredT('string'), b: optionalT('number') }) :
+          throwError(`Unknown type: '${initialValue.type}'`)
+        )
+      }
+    )
+  },
+  onSubmit() {}
+})
+
+{
+  const result = snapshot.get(form.fields.a)
+  expectNotAny(result)
+  expectNotNever(result)
+  expectAssignable<
+    {
+      invalid: boolean,
+      value: string | undefined,
+      error: Falsy | ValidationError
+    },
+    Prepared<typeof result>
+  >
+}
+{
+  const result = snapshot.get(form.fields.b)
+  expectNotAny(result)
+  expectNotNever(result)
+  expectAssignable<
+    {
+      invalid: boolean,
+      value: number | undefined,
+      error: Falsy | ValidationError
+    },
+    Prepared<typeof result>
+  >
+}
+{
+  const result = snapshot.get(form.fields.c)
+  expectNotAny(result)
+  expectNotNever(result)
+  expectAssignable<
+    {
+      invalid: boolean,
+      value: {
+        a: string | undefined,
+        b: number | undefined,
+      },
+      error: {
+        self: Falsy | ValidationError,
+        children: {
+          a: Falsy | ValidationError,
+          b: Falsy | ValidationError,
+        }
+      }
+    },
+    Prepared<typeof result>
+  >
+}
+{
+  const result = snapshot.get(form.fields.d)
+  expectNotAny(result)
+  expectNotNever(result)
+  expectAssignable<
+    {
+      invalid: boolean,
+      value: {
+        a: string | undefined,
+        b: number | undefined,
+      }[],
+      error: {
+        self: Falsy | ValidationError,
+        children: {
+          self: Falsy | ValidationError,
+          children: {
+            a: Falsy | ValidationError,
+            b: Falsy | ValidationError,
+          }
+        }[]
+      }
+    },
+    Prepared<typeof result>
+  >
+}
+{
+  const result = snapshot.get(form.fields.e)
+  expectNotAny(result)
+  expectNotNever(result)
+  expectAssignable<
+    {
+      invalid: boolean,
+      value: ({ type: string, a: string | undefined } | { type: string, b: number | undefined })[],
+      error: {
+        self: Falsy | ValidationError,
+        children: (
+          {
+            self: Falsy | ValidationError,
+            children:
+              { type: Falsy | ValidationError, a: Falsy | ValidationError } |
+              { type: Falsy | ValidationError, b: Falsy | ValidationError }
+          }
+        )[]
+      }
+    },
+    Prepared<typeof result>
+  >
+}
+
+{
+  const result = snapshot.get(form)
+}
+
+function throwError(m: string): never { throw new Error(m) }

package/src/state.js

@@ -1,3 +1,10 @@
+/** @import { Field, State } from './types.ts' */
+
+/**
+ * @template T
+ * @arg {T} initialState
+ * @returns {State.ReadWrite<T>}
+ */
 export function createState(initialState) {
   let state = initialState
   let listeners = new Set()
@@ -20,6 +27,19 @@ export function createState(initialState) {
   }
 }
 
+/**
+ * @template T
+ * @template {Field} R
+ * @template S
+ * @arg {{
+ *   state: State.ReadonlyWithHistory<T>,
+ *   childrenFromState: (value: T) => R[],
+ *   notify: State.Subscription<T | S>,
+ *   subscribeToChild: (child: R, notify: State.Subscription<S>) => State.Unsubscribe,
+ *   onlyNotifyOnChildChange?: boolean,
+ * }} props
+ * @returns {State.Unsubscribe}
+ */
 export function subscribeToAll({
   state,
   childrenFromState,
@@ -37,7 +57,7 @@ export function subscribeToAll({
       unsubscribeChildren = subscribeToChildren({ children: newChildren, notify, subscribeToChild })
     }
     if (onlyNotifyOnChildChange && !childrenChanged) return
-    notify(newState, oldState)
+    notify(newState)
   })
 
   return () => {
@@ -46,6 +66,16 @@ export function subscribeToAll({
   }
 }
 
+/**
+ * @template {Field} R
+ * @template {State.SubscriptionWithHistory<any> | State.Subscription<any>} N
+ * @arg {{
+*   children: R[],
+*   notify: N,
+*   subscribeToChild: (child: R, notify: N) => State.Unsubscribe,
+* }} props
+* @returns {State.Unsubscribe}
+*/
 export function subscribeToChildren({ children, notify, subscribeToChild }) {
   return children.reduce(
     (unsubscribePrevious, x) => {

package/src/type-helpers.js

@@ -0,0 +1,12 @@
+/**
+ * @template const T
+ * @arg {T} x
+ */
+export function asConst(x) {
+  return x
+}
+
+/** @arg {any} x */
+export function asAny(x) {
+  return x
+}

package/src/type.test.helpers.ts

@@ -0,0 +1,47 @@
+/** We need this because `never` matches all types (if we mistakenly infer an any or an infer type, we have problem) */
+export function expectNotNever<T>(...expectNotNever: [T] & NotNever<T>) {}
+type NotNever<T> = CheckNever<T, [T]>
+
+type CheckNever<T, IfNotNever> =
+  T extends Array<infer X> ? CheckNever<X, IfNotNever> :
+  T extends Record<any, infer X> ? CheckNever<X, IfNotNever> :
+  T extends never ? [] :
+  IfNotNever
+
+/** We need this because `any` matches all types (if we mistakenly infer an any or an infer type, we have problem) */
+export function expectNotAny<Expected>(actual: NotAny<Expected>) {}
+type NotAny<T> = 0 extends (1 & T) ? never : T
+
+export function expectAssignable<const Expected, const Actual extends Expected & NoExtraKeys<Actual, Expected> & MarkedPrepared>() {}
+
+// We want our `Expected` types to be precise and not miss any additional keys
+type NoExtraKeys<T, U> = {
+  [K in keyof T]: K extends keyof U ? T[K] : `Key '${K extends string ? K : '[unknown key]'}' was not expected`
+}
+
+// Needed to force `Prepared<typeof value>` instead of `typeof value` in `Actual` of `expectAssignable`
+type MarkedPrepared = {
+  __isPrepared: any
+}
+
+// Converting `any` into `unknown` helps to make sure `{ a: any }` does not match `{ a: { b: any } }`
+export type Prepared<T> =
+  MarkedPrepared & ReplaceAnyWithUnknown<T>
+
+type ReplaceAnyWithUnknown<T> =
+  0 extends (1 & T) ? unknown & Any :
+  T extends ((...args: infer A) => infer R) ? ((...args: DeepPrepareTuple<A>) => ReplaceAnyWithUnknown<R>) :
+  [T] extends [readonly (infer U)[]]
+    ? { [K in keyof T]: ReplaceAnyWithUnknown<T[K]> }
+    :
+  T extends object
+    ? { [K in keyof T]: ReplaceAnyWithUnknown<T[K]> }
+    :
+  T
+
+// `any` matches with anything, so for better error reporting we replace it
+type Any = { __any__: any }
+
+type DeepPrepareTuple<T> = T extends [infer A, ...infer X]
+  ? [ReplaceAnyWithUnknown<A>, ...DeepPrepareTuple<X>]
+  : []