@kaliber/forms 2.1.1 → 3.0.0-beta.0

package/src/hooks.type.test.ts

@@ -0,0 +1,164 @@
+import {
+  useArrayFormField,
+  useBooleanFormField,
+  useForm,
+  useFormField,
+  useFormFieldSnapshot,
+  useFormFieldsValues,
+  useFormFieldValue,
+  useNumberFormField,
+  useObjectFormField
+} from './hooks'
+import { array, object } from './schema'
+import { expectAssignable, expectNotAny, expectNotNever, Prepared } from './type.test.helpers.ts'
+import { Field, Snapshot, State } from './types.ts'
+import { optionalT } from './validation'
+
+const { form } = useForm({
+  fields: {
+    a: optionalT('string'),
+    b: optionalT('number'),
+    c: optionalT('boolean'),
+    d: object({
+      a: optionalT('string'),
+      b: optionalT('number'),
+      c: optionalT('boolean'),
+    }),
+    e: array({
+      a: optionalT('string'),
+      b: optionalT('number'),
+      c: optionalT('boolean'),
+    })
+  },
+  onSubmit() {}
+})
+
+expectNotAny(form)
+expectNotNever(form)
+expectAssignable<
+  Field.Object<{
+    a: Field.Basic<string>,
+    b: Field.Basic<number>,
+    c: Field.Basic<boolean>,
+    d: Field.Object<{
+      a: Field.Basic<string>,
+      b: Field.Basic<number>,
+      c: Field.Basic<boolean>,
+    }>,
+    e: Field.Array<{
+      a: Field.Basic<string>,
+      b: Field.Basic<number>,
+      c: Field.Basic<boolean>,
+    }>
+  }>,
+  Prepared<typeof form>
+>
+
+const formFieldValue = useFormFieldValue(form.fields.a)
+expectAssignable<string, Prepared<typeof formFieldValue>>
+
+const formFieldsValues = useFormFieldsValues([form.fields.a, form.fields.b])
+expectAssignable<[string, number], Prepared<typeof formFieldsValues>>
+
+const formField = useFormField(form.fields.a)
+expectAssignable<
+  {
+    name: string
+    state: State.Basic<string>
+    eventHandlers: {
+        onBlur(): void
+        onFocus(): void
+        onChange(eOrValue: string | Field.Event<string>): void
+    }
+  },
+  Prepared<typeof formField>
+>
+
+const numberFormField = useNumberFormField(form.fields.b)
+expectAssignable<
+  {
+    name: string
+    state: State.Basic<string | number>
+    eventHandlers: {
+        onBlur(): void
+        onFocus(): void
+        onChange(e: { target: { value: string } }): void
+    }
+  },
+  Prepared<typeof numberFormField>
+>
+
+const booleanFormField = useBooleanFormField(form.fields.c)
+expectAssignable<
+  {
+    name: string
+    state: State.Basic<boolean>
+    eventHandlers: {
+        onBlur(): void
+        onFocus(): void
+        onChange(e: { target: { checked: boolean } }): void
+    }
+  },
+  Prepared<typeof booleanFormField>
+>
+
+const objectFormField = useObjectFormField(form.fields.d)
+expectAssignable<
+  {
+    name: string
+    state: State.Common
+    fields: {
+        a: Field.Basic<string>
+        b: Field.Basic<number>
+        c: Field.Basic<boolean>
+    }
+  },
+  Prepared<typeof objectFormField>
+>
+
+const arrayFormField = useArrayFormField(form.fields.e)
+expectAssignable<
+  {
+    name: string
+    state: State.Array<Field.Object<{
+        a: Field.Basic<string>
+        b: Field.Basic<number>
+        c: Field.Basic<boolean>
+    }>>
+    helpers: {
+        add(initialValue: {
+          a?: string
+          b?: number
+          c?: boolean
+        }): void
+        remove(entry: Field.Object<{
+          a: Field.Basic<string>
+          b: Field.Basic<number>
+          c: Field.Basic<boolean>
+        }>): void
+    }
+  },
+  Prepared<typeof arrayFormField>
+>
+
+const formFieldSnapshot = useFormFieldSnapshot(form)
+expectNotAny(formFieldSnapshot)
+expectNotNever(formFieldSnapshot)
+expectAssignable<
+  Snapshot.Object<{
+    a: Field.Basic<string>,
+    b: Field.Basic<number>,
+    c: Field.Basic<boolean>,
+    d: Field.Object<{
+      a: Field.Basic<string>,
+      b: Field.Basic<number>,
+      c: Field.Basic<boolean>,
+    }>,
+    e: Field.Array<{
+      a: Field.Basic<string>,
+      b: Field.Basic<number>,
+      c: Field.Basic<boolean>,
+    }>
+  }>,
+  Prepared<typeof formFieldSnapshot>
+>

package/src/normalize.js

@@ -1,5 +1,13 @@
-export function normalize(field, name) {
-  return (
+/** @import { FieldSchema, NormalizedField, Validate, ValidationContext, ValidationFunction } from './types.ts' */
+
+/**
+ * @template {FieldSchema} T
+ *
+ * @arg {T} field
+ * @arg {string} [name]
+ */
+export function normalize(field, name = '') {
+  return /** @type {NormalizedField.FromFieldSchema<T>} */ (
     convertValidationFunction(field, name) ||
     convertValidationArray(field, name) ||
     convertArrayField(field, name) ||
@@ -8,38 +16,83 @@ export function normalize(field, name) {
   )
 }
 
-function convertValidationFunction(x, name) {
-  return x instanceof Function &&
-    { type: 'basic', validate: toValidationFunction(x, name) }
+/**
+ * @arg {FieldSchema} field
+ * @arg {string} name
+ * @returns {false | NormalizedField.Basic}
+ */
+function convertValidationFunction(field, name) {
+  return field instanceof Function &&
+    { type: 'basic', validate: toValidationFunction(field, name) }
 }
-function convertValidationArray(x, name) {
-  return x instanceof Array &&
-    { type: 'basic', validate: toValidationFunction(x, name) }
+
+/**
+ * @arg {FieldSchema} field
+ * @arg {string} name
+ * @returns {false | NormalizedField.Basic}
+ */
+function convertValidationArray(field, name) {
+  return field instanceof Array &&
+    { type: 'basic', validate: toValidationFunction(field, name) }
 }
-function convertArrayField(x, name) {
-  return x && 'type' in x && x.type === 'array' &&
-    { type: 'array', validate: toValidationFunction(x.validate, name), fields: x.fields }
+
+/**
+ * @arg {FieldSchema} field
+ * @arg {string} name
+ * @returns {null | false | NormalizedField.Array}
+ */
+function convertArrayField(field, name) {
+  return field && 'type' in field && field.type === 'array' &&
+    { type: 'array', validate: toValidationFunction(field.validate, name), fields: field.fields }
 }
-function convertObjectField(x, name) {
-  return x && 'type' in x && x.type === 'object' &&
-    { type: 'object', validate: toValidationFunction(x.validate, name), fields: x.fields }
+
+/**
+ * @arg {FieldSchema} field
+ * @arg {string} name
+ * @returns {null | false | NormalizedField.Object}
+ */
+function convertObjectField(field, name) {
+  return field && 'type' in field && field.type === 'object' &&
+    { type: 'object', validate: toValidationFunction(field.validate, name), fields: field.fields }
 }
-function convertSimpleField(x, name) {
-  return { type: 'basic', validate: toValidationFunction(x && x.validate, name) }
+
+/**
+ * @arg {FieldSchema} field
+ * @arg {string} name
+ * @returns {NormalizedField.Basic}
+ */
+function convertSimpleField(field, name) {
+  return { type: 'basic', validate: toValidationFunction(field && 'validate' in field && field.validate, name) }
 }
 
-function toValidationFunction(x = [], name) {
-  const result = [].concat(x).reduce(
-    (previous, next) => {
-      const combined = previous && next && ((...args) => previous(...args) || next(...args))
-      return combined || next || previous
-    },
-    null
-  )
+/**
+ * @arg {false | undefined | Validate} fOrArrayOfF
+ * @param {string} name
+ * @returns {null | ValidationFunction}
+ */
+function toValidationFunction(fOrArrayOfF, name) {
+  const result = /** @type {(false | undefined | null | ValidationFunction)[]} */ ([])
+    .concat(fOrArrayOfF)
+    .reduce(
+      /** @arg {null | ValidationFunction} previous */
+      (previous, next) => {
+        const combined = previous && next && (
+          /** @arg {any} value @arg {ValidationContext} context */
+          (value, context) => previous(value, context) || next(value, context)
+        )
+        return combined || next || previous
+      },
+      null
+    )
 
-  return result && withBetterError(result, name)
+  return result ? withBetterError(result, name) : null
 }
 
+/**
+ * @arg {ValidationFunction} f
+ * @arg {string} name
+ * @returns {ValidationFunction}
+ */
 function withBetterError(f, name) {
   return (...args) => {
     try {

package/src/normalize.type.test.ts

@@ -0,0 +1,125 @@
+import { normalize } from './normalize'
+import { array, object } from './schema'
+import { asConst } from './type-helpers'
+import { expectAssignable, expectNotAny, expectNotNever, Prepared } from './type.test.helpers'
+import { ValidationFunction } from './types'
+import { email, number, optional, required } from './validation'
+
+const noValidation = optional
+const singleValidation = email
+const multipleValidation = asConst([required, number])
+const objectInput = {
+  noValidation,
+  singleValidation,
+  multipleValidation,
+}
+const simpleObjectSchema = object(objectInput)
+const simpleArraySchema = array(objectInput)
+const simpleObjectWithValidationSchema = object(value => validate(value), objectInput)
+const simpleArrayWithValidationSchema = array(value => validate(value), objectInput)
+type BaseObjectNormalizedField = {
+  type: 'object',
+  fields: {
+    noValidation: null,
+    singleValidation: ValidationFunction<string>,
+    multipleValidation: readonly [ValidationFunction, ValidationFunction<number>],
+  }
+}
+type BaseArrayNormalizedField = {
+  type: 'array',
+  fields: {
+    noValidation: null,
+    singleValidation: ValidationFunction<string>,
+    multipleValidation: readonly [ValidationFunction, ValidationFunction<number>],
+  }
+}
+type BasicNormalizedField<T> = {
+  type: 'basic',
+  validate: T
+}
+
+{
+  const noValidationNormalizedField = normalize(noValidation)
+  expectNotAny(noValidationNormalizedField)
+  expectNotNever(noValidationNormalizedField)
+  expectAssignable<
+    BasicNormalizedField<null>,
+    Prepared<typeof noValidationNormalizedField>
+  >
+}
+
+{
+  const multipleValidationNormalizedField = normalize(multipleValidation)
+  expectNotAny(multipleValidationNormalizedField)
+  expectNotNever(multipleValidationNormalizedField)
+  expectAssignable<
+    BasicNormalizedField<ValidationFunction<number>>,
+    Prepared<typeof multipleValidationNormalizedField>
+  >
+}
+
+{
+  const singleValidationNormalizedField = normalize(singleValidation)
+  expectNotAny(singleValidationNormalizedField)
+  expectNotNever(singleValidationNormalizedField)
+  expectAssignable<
+    BasicNormalizedField<ValidationFunction<string>>,
+    Prepared<typeof singleValidationNormalizedField>
+  >
+}
+
+{
+  const simpleObjectNormalizedField = normalize(simpleObjectSchema)
+  expectNotAny(simpleObjectNormalizedField)
+  expectNotNever(simpleObjectNormalizedField)
+  expectAssignable<
+    BaseObjectNormalizedField & { validate: null },
+    Prepared<typeof simpleObjectNormalizedField>
+  >
+}
+
+{
+  const simpleObjectWithValidationNormalizedField = normalize(simpleObjectWithValidationSchema)
+  expectNotAny(simpleObjectWithValidationNormalizedField)
+  expectNotNever(simpleObjectWithValidationNormalizedField)
+  expectAssignable<
+    BaseObjectNormalizedField & {
+      validate: ValidationFunction<{
+        noValidation: unknown,
+        singleValidation: string,
+        multipleValidation: number,
+      }>
+    },
+    Prepared<typeof simpleObjectWithValidationNormalizedField>
+  >
+}
+
+{
+  const simpleArrayNormalizedField = normalize(simpleArraySchema)
+  expectNotAny(simpleArrayNormalizedField)
+  expectNotNever(simpleArrayNormalizedField)
+  expectAssignable<
+    BaseArrayNormalizedField & { validate: null },
+    Prepared<typeof simpleArrayNormalizedField>
+  >
+}
+
+{
+  const simpleArrayWithValidationNormalizedField = normalize(simpleArrayWithValidationSchema)
+  expectNotAny(simpleArrayWithValidationNormalizedField)
+  expectNotNever(simpleArrayWithValidationNormalizedField)
+  expectAssignable<
+    BaseArrayNormalizedField & {
+      validate: ValidationFunction<{
+        noValidation: unknown,
+        singleValidation: string,
+        multipleValidation: number,
+      }[]>
+    },
+    Prepared<typeof simpleArrayWithValidationNormalizedField>
+  >
+}
+
+function validate<T>(value: T) {
+  return value === 'failure' && { id: 'error' }
+}

package/src/schema.js

@@ -1,16 +1,40 @@
+/** @import { Expand, FieldInput, Validate } from './types.ts' */
+
 /**
- * @template A, B
- * @param {A} fieldsOrValidate
- * @param {B} [fields]
+ * @template {Validate<FieldInput.ObjectToValue<B>>} const A
+ * @template {FieldInput.Object} const B
+ *
+ * @overload
+ * @arg {A} fieldsOrValidate
+ * @arg {B} fields
+ * @returns {ReturnType<typeof body<'object', A, B>>}
+ *
+ * @overload
+ * @arg {B} fieldsOrValidate
+ * @returns {ReturnType<typeof body<'object', B, undefined>>}
+ *
+ * @arg {A | B} fieldsOrValidate
+ * @arg {B} [fields]
  */
 export function object(fieldsOrValidate, fields) {
   return body('object', fieldsOrValidate, fields)
 }
 
 /**
- * @template A, B
- * @param {A} fieldsOrValidate
- * @param {B} [fields]
+ * @template {Validate<Expand<FieldInput.ArrayToValue<B>>>} const A
+ * @template {FieldInput.Array} const B
+ *
+ * @overload
+ * @arg {A} fieldsOrValidate
+ * @arg {B} fields
+ * @returns {ReturnType<typeof body<'array', A, B>>}
+ *
+ * @overload
+ * @arg {B} fieldsOrValidate
+ * @returns {ReturnType<typeof body<'array', B, undefined>>}
+ *
+ * @arg {A | B} fieldsOrValidate
+ * @arg {B} [fields]
  */
 export function array(fieldsOrValidate, fields) {
   return body('array', fieldsOrValidate, fields)
@@ -20,13 +44,17 @@ export function array(fieldsOrValidate, fields) {
  * @template {string} T
  * @template A, B
  *
- * @param {T} type
- * @param {A} fieldsOrValidate
- * @param {B} [fields]
+ * @arg {T} type
+ * @arg {A} fieldsOrValidate
+ * @arg {B} [fields]
  *
- * @returns {Expand<{ type: T } & IfAny<B, { fields: A }, { fields: B, validate: A }>>}
+ * @returns {{ type: T } & (
+ *   B extends undefined ? { fields: A } :
+ *   B extends infer X ? { fields: X, validate: A } :
+ *   never
+ * )}
  */
 function body(type, fieldsOrValidate, fields) {
-  // @ts-ignore - if you want to remove this @ts-ignore: good luck and please leave a comment afterwards *
+  // @ts-expect-error - if you want to remove this @ts-ignore: good luck and please leave a comment afterwards *
   return { type, fields: fields || fieldsOrValidate, validate: fields && fieldsOrValidate }
 }

package/src/schema.type.test.ts

@@ -0,0 +1,159 @@
+import { email, number, optional, required } from './validation'
+import { array, object } from './schema'
+import { asConst } from './type-helpers'
+import type { InitialValue, Validate } from './types.ts'
+import { expectAssignable, expectNotAny, expectNotNever, Prepared } from './type.test.helpers.ts'
+
+const simpleObjectInput = asConst({
+  noValidation: optional,
+  singleValidation: email,
+  multipleValidation: [required, number],
+})
+type ObjectSchema<Fields> = {
+  type: 'object',
+  fields: Fields,
+}
+type ArraySchema<Fields> = {
+  type: 'array',
+  fields: Fields,
+}
+type SimpleObjectSchema = ObjectSchema<SimpleObjectFields>
+
+type SimpleObjectFields = {
+  noValidation: Validate<unknown>,
+  singleValidation: Validate<string>,
+  multipleValidation: readonly [Validate<any>, Validate<number>],
+}
+type SimpleObjectValues = {
+  noValidation: unknown,
+  singleValidation: string,
+  multipleValidation: number,
+}
+
+{
+  const simpleObjectSchema = object(simpleObjectInput)
+  expectNotAny(simpleObjectSchema)
+  expectAssignable<SimpleObjectSchema, Prepared<typeof simpleObjectSchema>>()
+}
+
+{
+  const simpleObjectWithValidationSchema = object(
+    (value) => {
+      expectNotNever(value)
+      expectNotAny(value)
+      expectAssignable<SimpleObjectValues, Prepared<typeof value>>()
+
+      return validate(value)
+    },
+    simpleObjectInput
+  )
+  expectNotAny(simpleObjectWithValidationSchema)
+  expectAssignable<
+    SimpleObjectSchema & { validate: Validate<SimpleObjectValues> },
+    Prepared<typeof simpleObjectWithValidationSchema>
+  >
+}
+
+const nestedObjectInput = { nested: object(simpleObjectInput) }
+type NestedObjectSchema = ObjectSchema<{ nested: SimpleObjectSchema }>
+{
+  const nestedObjectSchema = object(nestedObjectInput)
+  expectNotAny(nestedObjectSchema)
+  expectAssignable<NestedObjectSchema, Prepared<typeof nestedObjectSchema>>
+}
+
+{
+  const nestedObjectWithValidationSchema = object(
+    value => {
+      expectNotAny(value)
+      expectNotNever(value)
+      expectAssignable<{ nested: SimpleObjectValues }, Prepared<typeof value>>
+
+      return validate(value)
+    },
+    nestedObjectInput
+  )
+  expectNotAny(nestedObjectWithValidationSchema)
+  expectAssignable<
+    NestedObjectSchema & { validate: Validate<{ nested: SimpleObjectValues }> },
+    Prepared<typeof nestedObjectWithValidationSchema>
+  >
+}
+
+{
+  const simpleArraySchema = array(simpleObjectInput)
+  expectNotAny(simpleArraySchema)
+  expectAssignable<ArraySchema<SimpleObjectFields>, Prepared<typeof simpleArraySchema>>
+}
+
+{
+  const simpleArrayWithValidationSchema = array(
+    value => {
+      expectNotAny(value)
+      expectNotNever(value)
+      expectAssignable<SimpleObjectValues[], Prepared<typeof value>>
+
+      return validate(value)
+    },
+    simpleObjectInput
+  )
+  expectNotAny(simpleArrayWithValidationSchema)
+  expectAssignable<
+    ArraySchema<SimpleObjectFields> & { validate: Validate<SimpleObjectValues[]> },
+    Prepared<typeof simpleArrayWithValidationSchema>
+  >
+}
+
+const inputA = asConst({ type: validate<'a'>, a: object(simpleObjectInput) })
+const inputB = asConst({ type: validate<'b'>, b: object(simpleObjectInput) })
+type HeterogeneousInitialValues = InitialValue<typeof inputA | typeof inputB>
+
+{
+  type InitialValues = InitialValue<typeof inputA | typeof inputB>
+
+  const heterogeneousArraySchema = array(
+    (initialValue: InitialValues) =>
+      initialValue.type === 'a' ? inputA : inputB
+  )
+  expectNotAny(heterogeneousArraySchema)
+  expectAssignable<
+    ArraySchema<(initialValues: InitialValues) =>
+      { type: Validate<'a'>, a: SimpleObjectSchema } |
+      { type: Validate<'b'>, b: SimpleObjectSchema }
+    >,
+    Prepared<typeof heterogeneousArraySchema>
+  >
+}
+
+{
+  const heterogeneousArrayWithValidationSchema = array(
+    value => {
+      expectNotAny(value)
+      expectNotNever(value)
+      expectAssignable<
+        ({ type: 'a', a: SimpleObjectValues } | { type: 'b', b: SimpleObjectValues })[],
+        Prepared<typeof value>
+      >
+
+      return validate(value)
+    },
+    (initialValue: HeterogeneousInitialValues) =>
+      initialValue.type === 'a' ? inputA :
+      initialValue.type === 'b' ? inputB :
+      throwError(`Unknown type: '${initialValue.type}'`)
+  )
+  expectNotAny(heterogeneousArrayWithValidationSchema)
+  expectAssignable<
+    ArraySchema<(initialValues: HeterogeneousInitialValues) =>
+      { type: Validate<'a'>, a: SimpleObjectSchema } |
+      { type: Validate<'b'>, b: SimpleObjectSchema }
+    > & { validate: Validate<({ type: 'a', a: SimpleObjectValues } | { type: 'b', b: SimpleObjectValues })[]> },
+    Prepared<typeof heterogeneousArrayWithValidationSchema>
+  >
+}
+
+function validate<T>(value: T) {
+  return value === 'failure' && { id: 'error' }
+}
+
+function throwError(m: string): never { throw new Error(m) }