@regle/schemas 0.7.0

package/dist/regle-schemas.d.cts

@@ -0,0 +1,411 @@
+import { RegleShortcutDefinition, RegleCommonStatus, JoinDiscriminatedUnions, RegleErrorTree, RegleRuleStatus, RegleCollectionErrors, MismatchInfo, DeepReactiveState, DeepMaybeRef, RegleBehaviourOptions, LocalRegleBehaviourOptions, NoInferLegacy, PrimitiveTypes } from '@regle/core';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { Raw, UnwrapNestedRefs, MaybeRef, Ref } from 'vue';
+
+/**
+Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+
+@category Type
+*/
+type Primitive =
+	| null
+	| undefined
+	| string
+	| number
+	| boolean
+	| symbol
+	| bigint;
+
+declare global {
+	// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
+	interface SymbolConstructor {
+		readonly observable: symbol;
+	}
+}
+
+declare const emptyObjectSymbol: unique symbol;
+
+/**
+Represents a strictly empty plain object, the `{}` value.
+
+When you annotate something as the type `{}`, it can be anything except `null` and `undefined`. This means that you cannot use `{}` to represent an empty plain object ([read more](https://stackoverflow.com/questions/47339869/typescript-empty-object-and-any-difference/52193484#52193484)).
+
+@example
+```
+import type {EmptyObject} from 'type-fest';
+
+// The following illustrates the problem with `{}`.
+const foo1: {} = {}; // Pass
+const foo2: {} = []; // Pass
+const foo3: {} = 42; // Pass
+const foo4: {} = {a: 1}; // Pass
+
+// With `EmptyObject` only the first case is valid.
+const bar1: EmptyObject = {}; // Pass
+const bar2: EmptyObject = 42; // Fail
+const bar3: EmptyObject = []; // Fail
+const bar4: EmptyObject = {a: 1}; // Fail
+```
+
+Unfortunately, `Record<string, never>`, `Record<keyof any, never>` and `Record<never, never>` do not work. See {@link https://github.com/sindresorhus/type-fest/issues/395 #395}.
+
+@category Object
+*/
+type EmptyObject = {[emptyObjectSymbol]?: never};
+
+/**
+Returns a boolean for whether the two given types are equal.
+
+@link https://github.com/microsoft/TypeScript/issues/27024#issuecomment-421529650
+@link https://stackoverflow.com/questions/68961864/how-does-the-equals-work-in-typescript/68963796#68963796
+
+Use-cases:
+- If you want to make a conditional branch based on the result of a comparison of two types.
+
+@example
+```
+import type {IsEqual} from 'type-fest';
+
+// This type returns a boolean for whether the given array includes the given item.
+// `IsEqual` is used to compare the given array at position 0 and the given item and then return true if they are equal.
+type Includes<Value extends readonly any[], Item> =
+	Value extends readonly [Value[0], ...infer rest]
+		? IsEqual<Value[0], Item> extends true
+			? true
+			: Includes<rest, Item>
+		: false;
+```
+
+@category Type Guard
+@category Utilities
+*/
+type IsEqual<A, B> =
+	(<G>() => G extends A ? 1 : 2) extends
+	(<G>() => G extends B ? 1 : 2)
+		? true
+		: false;
+
+/**
+Extract the element of an array that also works for array union.
+
+Returns `never` if T is not an array.
+
+It creates a type-safe way to access the element type of `unknown` type.
+*/
+type ArrayElement<T> = T extends readonly unknown[] ? T[0] : never;
+
+/**
+Returns a boolean for whether either of two given types are true.
+
+Use-case: Constructing complex conditional types where multiple conditions must be satisfied.
+
+@example
+```
+import type {Or} from 'type-fest';
+
+Or<true, false>;
+//=> true
+
+Or<false, false>;
+//=> false
+```
+
+@see {@link And}
+*/
+type Or<A extends boolean, B extends boolean> = [A, B][number] extends false
+	? false
+	: true extends [IsEqual<A, true>, IsEqual<B, true>][number]
+		? true
+		: never;
+
+/**
+Matches any primitive, `void`, `Date`, or `RegExp` value.
+*/
+type BuiltIns = Primitive | void | Date | RegExp;
+
+/**
+@see PartialDeep
+*/
+type PartialDeepOptions = {
+	/**
+	Whether to affect the individual elements of arrays and tuples.
+
+	@default false
+	*/
+	readonly recurseIntoArrays?: boolean;
+};
+
+/**
+Create a type from another type with all keys and nested keys set to optional.
+
+Use-cases:
+- Merging a default settings/config object with another object, the second object would be a deep partial of the default object.
+- Mocking and testing complex entities, where populating an entire object with its keys would be redundant in terms of the mock or test.
+
+@example
+```
+import type {PartialDeep} from 'type-fest';
+
+const settings: Settings = {
+	textEditor: {
+		fontSize: 14;
+		fontColor: '#000000';
+		fontWeight: 400;
+	}
+	autocomplete: false;
+	autosave: true;
+};
+
+const applySavedSettings = (savedSettings: PartialDeep<Settings>) => {
+	return {...settings, ...savedSettings};
+}
+
+settings = applySavedSettings({textEditor: {fontWeight: 500}});
+```
+
+By default, this does not affect elements in array and tuple types. You can change this by passing `{recurseIntoArrays: true}` as the second type argument:
+
+```
+import type {PartialDeep} from 'type-fest';
+
+interface Settings {
+	languages: string[];
+}
+
+const partialSettings: PartialDeep<Settings, {recurseIntoArrays: true}> = {
+	languages: [undefined]
+};
+```
+
+@category Object
+@category Array
+@category Set
+@category Map
+*/
+type PartialDeep<T, Options extends PartialDeepOptions = {}> = T extends BuiltIns | (((...arguments_: any[]) => unknown)) | (new (...arguments_: any[]) => unknown)
+	? T
+	: T extends Map<infer KeyType, infer ValueType>
+		? PartialMapDeep<KeyType, ValueType, Options>
+		: T extends Set<infer ItemType>
+			? PartialSetDeep<ItemType, Options>
+			: T extends ReadonlyMap<infer KeyType, infer ValueType>
+				? PartialReadonlyMapDeep<KeyType, ValueType, Options>
+				: T extends ReadonlySet<infer ItemType>
+					? PartialReadonlySetDeep<ItemType, Options>
+					: T extends object
+						? T extends ReadonlyArray<infer ItemType> // Test for arrays/tuples, per https://github.com/microsoft/TypeScript/issues/35156
+							? Options['recurseIntoArrays'] extends true
+								? ItemType[] extends T // Test for arrays (non-tuples) specifically
+									? readonly ItemType[] extends T // Differentiate readonly and mutable arrays
+										? ReadonlyArray<PartialDeep<ItemType | undefined, Options>>
+										: Array<PartialDeep<ItemType | undefined, Options>>
+									: PartialObjectDeep<T, Options> // Tuples behave properly
+								: T // If they don't opt into array testing, just use the original type
+							: PartialObjectDeep<T, Options>
+						: unknown;
+
+/**
+Same as `PartialDeep`, but accepts only `Map`s and as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialMapDeep<KeyType, ValueType, Options extends PartialDeepOptions> = {} & Map<PartialDeep<KeyType, Options>, PartialDeep<ValueType, Options>>;
+
+/**
+Same as `PartialDeep`, but accepts only `Set`s as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialSetDeep<T, Options extends PartialDeepOptions> = {} & Set<PartialDeep<T, Options>>;
+
+/**
+Same as `PartialDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialReadonlyMapDeep<KeyType, ValueType, Options extends PartialDeepOptions> = {} & ReadonlyMap<PartialDeep<KeyType, Options>, PartialDeep<ValueType, Options>>;
+
+/**
+Same as `PartialDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialReadonlySetDeep<T, Options extends PartialDeepOptions> = {} & ReadonlySet<PartialDeep<T, Options>>;
+
+/**
+Same as `PartialDeep`, but accepts only `object`s as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialObjectDeep<ObjectType extends object, Options extends PartialDeepOptions> = {
+	[KeyType in keyof ObjectType]?: PartialDeep<ObjectType[KeyType], Options>
+};
+
+type RegleSchemaMode = 'rules' | 'schema';
+type isModeRules<T> = T extends 'rules' ? true : false;
+type RegleSchemaModeOptions<T extends RegleSchemaMode = 'rules'> = {
+    mode?: T;
+};
+
+interface RegleSchema<TState extends Record<string, any>, TSchema extends Record<string, any>, TMode extends RegleSchemaMode = 'rules', TShortcuts extends RegleShortcutDefinition = {}> {
+    /**
+     * r$ is a reactive object containing the values, errors, dirty state and all the necessary validations properties you'll need to display informations.
+     *
+     * To see the list of properties: {@link https://reglejs.dev/core-concepts/validation-properties}
+     */
+    r$: Raw<RegleSchemaStatus<TState, TSchema, TMode, TShortcuts, true>>;
+}
+type RegleSchemaResult<TSchema extends unknown> = {
+    result: false;
+    data: PartialDeep<TSchema>;
+} | {
+    result: true;
+    data: TSchema;
+};
+/**
+ * @public
+ */
+type RegleSchemaStatus<TState extends Record<string, any> = Record<string, any>, TSchema extends Record<string, any> = Record<string, any>, TMode extends RegleSchemaMode = 'rules', TShortcuts extends RegleShortcutDefinition = {}, IsRoot extends boolean = false> = Omit<RegleCommonStatus<TState>, Or<isModeRules<TMode>, IsRoot> extends false ? '$pending' : ''> & {
+    /** Represents all the children of your object. You can access any nested child at any depth to get the relevant data you need for your form. */
+    readonly $fields: {
+        readonly [TKey in keyof JoinDiscriminatedUnions<TState>]: TKey extends keyof JoinDiscriminatedUnions<TSchema> ? InferRegleSchemaStatusType<NonNullable<JoinDiscriminatedUnions<TSchema>[TKey]>, JoinDiscriminatedUnions<TState>[TKey], TMode, TShortcuts> : never;
+    } & {
+        readonly [TKey in keyof JoinDiscriminatedUnions<TState> as TKey extends keyof JoinDiscriminatedUnions<TSchema> ? JoinDiscriminatedUnions<TSchema>[TKey] extends NonNullable<JoinDiscriminatedUnions<TSchema>[TKey]> ? TKey : never : never]-?: TKey extends keyof JoinDiscriminatedUnions<TSchema> ? InferRegleSchemaStatusType<NonNullable<JoinDiscriminatedUnions<TSchema>[TKey]>, JoinDiscriminatedUnions<TState>[TKey], TMode, TShortcuts> : never;
+    };
+    /** Collection of all the error messages, collected for all children properties and nested forms.
+     *
+     * Only contains errors from properties where $dirty equals true. */
+    readonly $errors: RegleErrorTree<TState>;
+    /** Collection of all the error messages, collected for all children properties. */
+    readonly $silentErrors: RegleErrorTree<TState>;
+    /** Will return a copy of your state with only the fields that are dirty. By default it will filter out nullish values or objects, but you can override it with the first parameter $extractDirtyFields(false). */
+    $extractDirtyFields: (filterNullishValues?: boolean) => PartialDeep<TState>;
+} & (Or<isModeRules<TMode>, IsRoot> extends true ? {
+    /** Sets all properties as dirty, triggering all rules. It returns a promise that will either resolve to false or a type safe copy of your form state. Values that had the required rule will be transformed into a non-nullable value (type only). */
+    $validate: () => Promise<RegleSchemaResult<TSchema>>;
+} : {}) & ([TShortcuts['nested']] extends [never] ? {} : {
+    [K in keyof TShortcuts['nested']]: ReturnType<NonNullable<TShortcuts['nested']>[K]>;
+});
+/**
+ * @public
+ */
+type InferRegleSchemaStatusType<TSchema extends unknown, TState extends unknown, TMode extends RegleSchemaMode = 'rules', TShortcuts extends RegleShortcutDefinition = {}> = NonNullable<TSchema> extends Array<infer A extends Record<string, any>> ? RegleSchemaCollectionStatus<A, TState extends Array<any> ? TState : [], TMode, TShortcuts> : NonNullable<TState> extends Date | File ? RegleSchemaFieldStatus<TSchema, TState, TMode, TShortcuts> : unknown extends TState ? RegleSchemaFieldStatus<TSchema extends EmptyObject ? unknown : TSchema, TState, TMode, TShortcuts> : NonNullable<TSchema> extends Record<string, any> ? RegleSchemaStatus<NonNullable<TState> extends Record<string, any> ? NonNullable<TState> : {}, NonNullable<TSchema>, TMode, TShortcuts> : RegleSchemaFieldStatus<TSchema, TState, TMode, TShortcuts>;
+/**
+ * @public
+ */
+type RegleSchemaFieldStatus<TSchema extends unknown, TState = any, TMode extends RegleSchemaMode = 'rules', TShortcuts extends RegleShortcutDefinition = {}> = Omit<RegleCommonStatus<TState>, isModeRules<TMode> extends false ? '$pending' : ''> & {
+    /** Collection of all the error messages, collected for all children properties and nested forms.
+     *
+     * Only contains errors from properties where $dirty equals true. */
+    readonly $errors: string[];
+    /** Collection of all the error messages, collected for all children properties and nested forms.  */
+    readonly $silentErrors: string[];
+    /** Will return a copy of your state with only the fields that are dirty. By default it will filter out nullish values or objects, but you can override it with the first parameter $extractDirtyFields(false). */
+    readonly $externalErrors?: string[];
+    /** Represents the inactive status. Is true when this state have empty rules */
+    readonly $inactive: boolean;
+    /** This is reactive tree containing all the declared rules of your field. To know more about the rule properties check the rules properties section */
+    readonly $rules: {
+        [`~validator`]: RegleRuleStatus<TState, []>;
+    };
+    /** Will return a copy of your state with only the fields that are dirty. By default it will filter out nullish values or objects, but you can override it with the first parameter $extractDirtyFields(false). */
+    $extractDirtyFields: (filterNullishValues?: boolean) => PartialDeep<TState>;
+} & (isModeRules<TMode> extends true ? {
+    /** Sets the property as dirty, triggering all rules. It returns a promise that will either resolve to false or a type safe copy of your form state. Values that had the required rule will be transformed into a non-nullable value (type only). */
+    $validate: () => Promise<RegleSchemaResult<TSchema>>;
+} : {}) & ([TShortcuts['fields']] extends [never] ? {} : {
+    [K in keyof TShortcuts['fields']]: ReturnType<NonNullable<TShortcuts['fields']>[K]>;
+});
+/**
+ * @public
+ */
+type RegleSchemaCollectionStatus<TSchema extends Record<string, any>, TState extends any[], TMode extends RegleSchemaMode = 'rules', TShortcuts extends RegleShortcutDefinition = {}> = Omit<RegleSchemaFieldStatus<TSchema, TState, TMode, TShortcuts>, '$errors' | '$silentErrors' | '$validate'> & {
+    /** Collection of status of every item in your collection. Each item will be a field you can access, or map on it to display your elements. */
+    readonly $each: Array<InferRegleSchemaStatusType<NonNullable<TSchema>, ArrayElement<TState>, TMode, TShortcuts>>;
+    /** Represents the status of the collection itself. You can have validation rules on the array like minLength, this field represents the isolated status of the collection. */
+    readonly $self: RegleSchemaFieldStatus<TSchema, TState, TMode, TShortcuts>;
+    /** Collection of all the error messages, collected for all children properties and nested forms.
+     *
+     * Only contains errors from properties where $dirty equals true. */
+    readonly $errors: RegleCollectionErrors<TSchema>;
+    /** Collection of all the error messages, collected for all children properties and nested forms.  */
+    readonly $silentErrors: RegleCollectionErrors<TSchema>;
+    /** Will return a copy of your state with only the fields that are dirty. By default it will filter out nullish values or objects, but you can override it with the first parameter $extractDirtyFields(false). */
+    $extractDirtyFields: (filterNullishValues?: boolean) => PartialDeep<TState>;
+} & (isModeRules<TMode> extends true ? {
+    /** Sets the property as dirty, triggering all rules. It returns a promise that will either resolve to false or a type safe copy of your form state. Values that had the required rule will be transformed into a non-nullable value (type only). */
+    $validate: () => Promise<RegleSchemaResult<TSchema>>;
+} : {}) & ([TShortcuts['collections']] extends [never] ? {} : {
+    [K in keyof TShortcuts['collections']]: ReturnType<NonNullable<TShortcuts['collections']>[K]>;
+});
+
+type useRegleSchemaFn<TShortcuts extends RegleShortcutDefinition<any> = never> = <TState extends Record<string, any>, TSchema extends StandardSchemaV1<Record<string, any>> & TValid, TMode extends RegleSchemaMode = never, TValid = UnwrapNestedRefs<TState> extends PartialDeep<StandardSchemaV1.InferInput<TSchema>, {
+    recurseIntoArrays: true;
+}> ? {} : MismatchInfo<UnwrapNestedRefs<TState>, PartialDeep<StandardSchemaV1.InferInput<TSchema>, {
+    recurseIntoArrays: true;
+}>>>(state: MaybeRef<TState> | DeepReactiveState<TState>, schema: MaybeRef<TSchema>, options?: Partial<DeepMaybeRef<RegleBehaviourOptions>> & LocalRegleBehaviourOptions<UnwrapNestedRefs<TState>, {}, never> & RegleSchemaModeOptions<TMode>) => RegleSchema<UnwrapNestedRefs<TState>, StandardSchemaV1.InferInput<TSchema>, [
+    TMode
+] extends [never] ? 'rules' : TMode, TShortcuts>;
+/**
+ * useRegle serves as the foundation for validation logic.
+ *
+ * It accepts the following inputs:
+ *
+ * @param state - This can be a plain object, a ref, a reactive object, or a structure containing nested refs.
+ * @param schema - These should align with the structure of your state.
+ * @param modifiers - customize regle behaviour
+ *
+ * ```ts
+ * import { useRegleSchema } from '@regle/schemas';
+  import * as v from 'valibot';
+
+  const { r$ } = useRegleSchema({ name: '' }, v.object({
+    name: v.pipe(v.string(), v.minLength(3))
+  }))
+ * ```
+ * Docs: {@link https://reglejs.dev/integrations/valibot#usage}
+ */
+declare const useRegleSchema: useRegleSchemaFn<RegleShortcutDefinition<any>>;
+
+/**
+ * ⚠️ Not compatible with `schema` mode
+ *
+ * Force dependency on any RPC schema
+ * ```ts
+ * const foo = ref('');
+ * withDeps(
+ *  v.pipe(v.string(), v.check((value) => value === foo.value)),
+ *  [foo]
+ * )
+ * ```
+ */
+declare function withDeps<TSchema extends StandardSchemaV1, TParams extends (Ref<unknown> | (() => unknown))[] = []>(schema: TSchema, depsArray: [...TParams]): TSchema & {
+    __depsArray: TParams;
+};
+
+interface inferValibotSchemaFn {
+    <TState extends Record<string, any>, TSchema extends StandardSchemaV1<Record<string, any>> & TValid, TValid = UnwrapNestedRefs<TState> extends PartialDeep<StandardSchemaV1.InferInput<TSchema>, {
+        recurseIntoArrays: true;
+    }> ? {} : MismatchInfo<UnwrapNestedRefs<TState>, PartialDeep<StandardSchemaV1.InferInput<TSchema>, {
+        recurseIntoArrays: true;
+    }>>>(state: MaybeRef<TState> | DeepReactiveState<TState> | undefined, rulesFactory: TSchema): NoInferLegacy<TSchema>;
+    <TState extends PrimitiveTypes, TSchema extends StandardSchemaV1 & TValid, TValid = TState extends StandardSchemaV1.InferInput<TSchema> ? {} : MismatchInfo<TState, StandardSchemaV1.InferInput<TSchema>>>(state: MaybeRef<TState>, rulesFactory: TSchema): NoInferLegacy<TSchema>;
+}
+/**
+ * Rule type helper to provide autocomplete and typecheck to your form rules or part of your form rules
+ * It will just return the rules without any processing.
+ *
+ * @param state - The state reference
+ * @param schema - Your valibot schema
+ */
+declare const inferSchema: inferValibotSchemaFn;
+
+/**
+ * Define a global regle configuration, where you can:
+ * - Define global modifiers
+ * - Define shortcuts
+ *
+ * It will return:
+ *
+ * - a `useRegleSchema` composable that can typecheck your custom rules
+ * - an `inferSchema` helper that can typecheck your custom rules
+ */
+declare function defineRegleSchemaConfig<TShortcuts extends RegleShortcutDefinition>({ modifiers, shortcuts, }: {
+    modifiers?: RegleBehaviourOptions;
+    shortcuts?: TShortcuts;
+}): {
+    useRegleSchema: useRegleSchemaFn<TShortcuts>;
+    inferSchema: inferValibotSchemaFn;
+};
+
+export { type InferRegleSchemaStatusType, type RegleSchema, type RegleSchemaCollectionStatus, type RegleSchemaFieldStatus, type RegleSchemaResult, type RegleSchemaStatus, defineRegleSchemaConfig, inferSchema, useRegleSchema, withDeps };