@oscarpalmer/jhunal 0.1.0 → 0.3.0

package/types/index.d.cts

@@ -1,3 +1,349 @@
 // Generated by dts-bundle-generator v9.5.1
 
+/**
+Convert a union type to an intersection type using [distributive conditional types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+
+Inspired by [this Stack Overflow answer](https://stackoverflow.com/a/50375286/2172153).
+
+@example
+```
+import type {UnionToIntersection} from 'type-fest';
+
+type Union = {the(): void} | {great(arg: string): void} | {escape: boolean};
+
+type Intersection = UnionToIntersection<Union>;
+//=> {the(): void; great(arg: string): void; escape: boolean};
+```
+
+A more applicable example which could make its way into your library code follows.
+
+@example
+```
+import type {UnionToIntersection} from 'type-fest';
+
+class CommandOne {
+	commands: {
+		a1: () => undefined,
+		b1: () => undefined,
+	}
+}
+
+class CommandTwo {
+	commands: {
+		a2: (argA: string) => undefined,
+		b2: (argB: string) => undefined,
+	}
+}
+
+const union = [new CommandOne(), new CommandTwo()].map(instance => instance.commands);
+type Union = typeof union;
+//=> {a1(): void; b1(): void} | {a2(argA: string): void; b2(argB: string): void}
+
+type Intersection = UnionToIntersection<Union>;
+//=> {a1(): void; b1(): void; a2(argA: string): void; b2(argB: string): void}
+```
+
+@category Type
+*/
+export type UnionToIntersection<Union> = (
+// `extends unknown` is always going to be the case and is used to convert the
+// `Union` into a [distributive conditional
+// type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+Union extends unknown ? (distributedUnion: Union) => void : never) extends ((mergedIntersection: infer Intersection) => void) ? Intersection & Union : never;
+/**
+Extract all optional keys from the given type.
+
+This is useful when you want to create a new type that contains different type values for the optional keys only.
+
+@example
+```
+import type {OptionalKeysOf, Except} from 'type-fest';
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+const REMOVE_FIELD = Symbol('remove field symbol');
+type UpdateOperation<Entity extends object> = Except<Partial<Entity>, OptionalKeysOf<Entity>> & {
+	[Key in OptionalKeysOf<Entity>]?: Entity[Key] | typeof REMOVE_FIELD;
+};
+
+const update1: UpdateOperation<User> = {
+	name: 'Alice'
+};
+
+const update2: UpdateOperation<User> = {
+	name: 'Bob',
+	luckyNumber: REMOVE_FIELD
+};
+```
+
+@category Utilities
+*/
+export type OptionalKeysOf<BaseType extends object> = BaseType extends unknown // For distributing `BaseType`
+ ? (keyof {
+	[Key in keyof BaseType as BaseType extends Record<Key, BaseType[Key]> ? never : Key]: never;
+}) & (keyof BaseType) // Intersect with `keyof BaseType` to ensure result of `OptionalKeysOf<BaseType>` is always assignable to `keyof BaseType`
+ : never; // Should never happen
+/**
+Extract all required keys from the given type.
+
+This is useful when you want to create a new type that contains different type values for the required keys only or use the list of keys for validation purposes, etc...
+
+@example
+```
+import type {RequiredKeysOf} from 'type-fest';
+
+declare function createValidation<Entity extends object, Key extends RequiredKeysOf<Entity> = RequiredKeysOf<Entity>>(field: Key, validator: (value: Entity[Key]) => boolean): ValidatorFn;
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+const validator1 = createValidation<User>('name', value => value.length < 25);
+const validator2 = createValidation<User>('surname', value => value.length < 25);
+```
+
+@category Utilities
+*/
+export type RequiredKeysOf<BaseType extends object> = BaseType extends unknown // For distributing `BaseType`
+ ? Exclude<keyof BaseType, OptionalKeysOf<BaseType>> : never; // Should never happen
+/**
+Returns a boolean for whether the given type is `never`.
+
+@link https://github.com/microsoft/TypeScript/issues/31751#issuecomment-498526919
+@link https://stackoverflow.com/a/53984913/10292952
+@link https://www.zhenghao.io/posts/ts-never
+
+Useful in type utilities, such as checking if something does not occur.
+
+@example
+```
+import type {IsNever, And} from 'type-fest';
+
+// https://github.com/andnp/SimplyTyped/blob/master/src/types/strings.ts
+type AreStringsEqual<A extends string, B extends string> =
+	And<
+		IsNever<Exclude<A, B>> extends true ? true : false,
+		IsNever<Exclude<B, A>> extends true ? true : false
+	>;
+
+type EndIfEqual<I extends string, O extends string> =
+	AreStringsEqual<I, O> extends true
+		? never
+		: void;
+
+function endIfEqual<I extends string, O extends string>(input: I, output: O): EndIfEqual<I, O> {
+	if (input === output) {
+		process.exit(0);
+	}
+}
+
+endIfEqual('abc', 'abc');
+//=> never
+
+endIfEqual('abc', '123');
+//=> void
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsNever<T> = [
+	T
+] extends [
+	never
+] ? true : false;
+/**
+Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+type PositionProps = {
+	top: number;
+	left: number;
+};
+
+type SizeProps = {
+	width: number;
+	height: number;
+};
+
+// In your editor, hovering over `Props` will show a flattened object with all the properties.
+type Props = Simplify<PositionProps & SizeProps>;
+```
+
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+interface SomeInterface {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+}
+
+type SomeType = {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+function fn(object: Record<string, unknown>): void {}
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+@see SimplifyDeep
+@category Object
+*/
+export type Simplify<T> = {
+	[KeyType in keyof T]: T[KeyType];
+} & {};
+/**
+Returns the last element of a union type.
+
+@example
+```
+type Last = LastOfUnion<1 | 2 | 3>;
+//=> 3
+```
+*/
+export type LastOfUnion<T> = UnionToIntersection<T extends any ? () => T : never> extends () => (infer R) ? R : never;
+/**
+Convert a union type into an unordered tuple type of its elements.
+
+"Unordered" means the elements of the tuple are not guaranteed to be in the same order as in the union type. The arrangement can appear random and may change at any time.
+
+This can be useful when you have objects with a finite set of keys and want a type defining only the allowed keys, but do not want to repeat yourself.
+
+@example
+```
+import type {UnionToTuple} from 'type-fest';
+
+type Numbers = 1 | 2 | 3;
+type NumbersTuple = UnionToTuple<Numbers>;
+//=> [1, 2, 3]
+```
+
+@example
+```
+import type {UnionToTuple} from 'type-fest';
+
+const pets = {
+  dog: '🐶',
+  cat: '🐱',
+  snake: '🐍',
+};
+
+type Pet = keyof typeof pets;
+//=> 'dog' | 'cat' | 'snake'
+
+const petList = Object.keys(pets) as UnionToTuple<Pet>;
+//=> ['dog', 'cat', 'snake']
+```
+
+@category Array
+*/
+export type UnionToTuple<T, L = LastOfUnion<T>> = IsNever<T> extends false ? [
+	...UnionToTuple<Exclude<T, L>>,
+	L
+] : [
+];
+export type GetKey<Value> = {
+	[Key in keyof Values]: Value extends Values[Key] ? Key : never;
+}[keyof Values];
+export type GetTypes<Value extends unknown[]> = Value extends [
+	infer Single
+] ? Single : Value;
+export type GetType<Value> = GetTypes<UnionToTuple<GetKey<Value>>>;
+export type InferProperty<Value> = Value extends Property ? Value["type"] extends keyof Values ? Values[Value["type"]] : Value["type"] extends (keyof Values)[] ? Values[Value["type"][number]] : never : never;
+export type InferValue<Value> = Value extends keyof Values ? Values[Value] : Value extends (keyof Values)[] ? Values[Value[number]] : never;
+export type Inferred<Model extends Schema> = {
+	[Key in InferredRequiredProperties<Model>]: Model[Key] extends Property ? InferProperty<Model[Key]> : InferValue<Model[Key]>;
+} & {
+	[Key in InferredOptionalProperties<Model>]?: Model[Key] extends Property ? InferProperty<Model[Key]> : never;
+};
+export type InferredOptionalProperties<Model extends Schema> = {
+	[Key in keyof Model]: Model[Key] extends Property ? Model[Key]["required"] extends false ? Key : never : never;
+}[keyof Model];
+export type InferredRequiredProperties<Model extends Schema> = {
+	[Key in keyof Model]: Model[Key] extends Property ? Model[Key]["required"] extends false ? never : Key : Key;
+}[keyof Model];
+export type OptionalProperty<Type> = {
+	required: false;
+	type: GetType<Type>;
+};
+export type Property = {
+	required?: boolean;
+	type: keyof Values | (keyof Values)[];
+};
+export type RequiredProperty<Type> = {
+	required: true;
+	type: GetType<Type>;
+};
+/**
+ * A schema for validating objects
+ */
+export type Schema = Record<string, keyof Values | (keyof Values)[] | Property>;
+/**
+ * A schematic for validating objects
+ */
+export type Schematic<Model> = {
+	/**
+	 * Does the value match the schema?
+	 */
+	is(value: unknown): value is Model;
+};
+export type Typed = Record<string, unknown>;
+/**
+ * A typed schema for validating objects
+ */
+export type TypedSchema<Model extends Typed> = Simplify<{
+	[Key in RequiredKeysOf<Model>]: GetType<Model[Key]> | RequiredProperty<Model[Key]>;
+} & {
+	[Key in OptionalKeysOf<Model>]: OptionalProperty<Model[Key]>;
+}>;
+export type Values = {
+	array: unknown[];
+	bigint: bigint;
+	boolean: boolean;
+	date: Date;
+	function: Function;
+	null: null;
+	number: number;
+	object: object;
+	string: string;
+	symbol: symbol;
+	undefined: undefined;
+};
+/**
+ * Create a schematic from a typed schema
+ */
+export declare function schematic<Model extends Typed>(schema: TypedSchema<Model>): Schematic<Model>;
+/**
+ * Create a schematic from a schema
+ */
+export declare function schematic<Model extends Schema>(schema: Model): Schematic<Inferred<Model>>;
+
 export {};

package/types/index.d.ts

@@ -1 +1,2 @@
-export {};
+export type { Schema, Schematic } from './model';
+export * from './schematic';

package/types/model.d.cts

@@ -0,0 +1,350 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+Convert a union type to an intersection type using [distributive conditional types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+
+Inspired by [this Stack Overflow answer](https://stackoverflow.com/a/50375286/2172153).
+
+@example
+```
+import type {UnionToIntersection} from 'type-fest';
+
+type Union = {the(): void} | {great(arg: string): void} | {escape: boolean};
+
+type Intersection = UnionToIntersection<Union>;
+//=> {the(): void; great(arg: string): void; escape: boolean};
+```
+
+A more applicable example which could make its way into your library code follows.
+
+@example
+```
+import type {UnionToIntersection} from 'type-fest';
+
+class CommandOne {
+	commands: {
+		a1: () => undefined,
+		b1: () => undefined,
+	}
+}
+
+class CommandTwo {
+	commands: {
+		a2: (argA: string) => undefined,
+		b2: (argB: string) => undefined,
+	}
+}
+
+const union = [new CommandOne(), new CommandTwo()].map(instance => instance.commands);
+type Union = typeof union;
+//=> {a1(): void; b1(): void} | {a2(argA: string): void; b2(argB: string): void}
+
+type Intersection = UnionToIntersection<Union>;
+//=> {a1(): void; b1(): void; a2(argA: string): void; b2(argB: string): void}
+```
+
+@category Type
+*/
+export type UnionToIntersection<Union> = (
+// `extends unknown` is always going to be the case and is used to convert the
+// `Union` into a [distributive conditional
+// type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+Union extends unknown ? (distributedUnion: Union) => void : never) extends ((mergedIntersection: infer Intersection) => void) ? Intersection & Union : never;
+/**
+Extract all optional keys from the given type.
+
+This is useful when you want to create a new type that contains different type values for the optional keys only.
+
+@example
+```
+import type {OptionalKeysOf, Except} from 'type-fest';
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+const REMOVE_FIELD = Symbol('remove field symbol');
+type UpdateOperation<Entity extends object> = Except<Partial<Entity>, OptionalKeysOf<Entity>> & {
+	[Key in OptionalKeysOf<Entity>]?: Entity[Key] | typeof REMOVE_FIELD;
+};
+
+const update1: UpdateOperation<User> = {
+	name: 'Alice'
+};
+
+const update2: UpdateOperation<User> = {
+	name: 'Bob',
+	luckyNumber: REMOVE_FIELD
+};
+```
+
+@category Utilities
+*/
+export type OptionalKeysOf<BaseType extends object> = BaseType extends unknown // For distributing `BaseType`
+ ? (keyof {
+	[Key in keyof BaseType as BaseType extends Record<Key, BaseType[Key]> ? never : Key]: never;
+}) & (keyof BaseType) // Intersect with `keyof BaseType` to ensure result of `OptionalKeysOf<BaseType>` is always assignable to `keyof BaseType`
+ : never; // Should never happen
+/**
+Extract all required keys from the given type.
+
+This is useful when you want to create a new type that contains different type values for the required keys only or use the list of keys for validation purposes, etc...
+
+@example
+```
+import type {RequiredKeysOf} from 'type-fest';
+
+declare function createValidation<Entity extends object, Key extends RequiredKeysOf<Entity> = RequiredKeysOf<Entity>>(field: Key, validator: (value: Entity[Key]) => boolean): ValidatorFn;
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+const validator1 = createValidation<User>('name', value => value.length < 25);
+const validator2 = createValidation<User>('surname', value => value.length < 25);
+```
+
+@category Utilities
+*/
+export type RequiredKeysOf<BaseType extends object> = BaseType extends unknown // For distributing `BaseType`
+ ? Exclude<keyof BaseType, OptionalKeysOf<BaseType>> : never; // Should never happen
+/**
+Returns a boolean for whether the given type is `never`.
+
+@link https://github.com/microsoft/TypeScript/issues/31751#issuecomment-498526919
+@link https://stackoverflow.com/a/53984913/10292952
+@link https://www.zhenghao.io/posts/ts-never
+
+Useful in type utilities, such as checking if something does not occur.
+
+@example
+```
+import type {IsNever, And} from 'type-fest';
+
+// https://github.com/andnp/SimplyTyped/blob/master/src/types/strings.ts
+type AreStringsEqual<A extends string, B extends string> =
+	And<
+		IsNever<Exclude<A, B>> extends true ? true : false,
+		IsNever<Exclude<B, A>> extends true ? true : false
+	>;
+
+type EndIfEqual<I extends string, O extends string> =
+	AreStringsEqual<I, O> extends true
+		? never
+		: void;
+
+function endIfEqual<I extends string, O extends string>(input: I, output: O): EndIfEqual<I, O> {
+	if (input === output) {
+		process.exit(0);
+	}
+}
+
+endIfEqual('abc', 'abc');
+//=> never
+
+endIfEqual('abc', '123');
+//=> void
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsNever<T> = [
+	T
+] extends [
+	never
+] ? true : false;
+/**
+Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+type PositionProps = {
+	top: number;
+	left: number;
+};
+
+type SizeProps = {
+	width: number;
+	height: number;
+};
+
+// In your editor, hovering over `Props` will show a flattened object with all the properties.
+type Props = Simplify<PositionProps & SizeProps>;
+```
+
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+interface SomeInterface {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+}
+
+type SomeType = {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+function fn(object: Record<string, unknown>): void {}
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+@see SimplifyDeep
+@category Object
+*/
+export type Simplify<T> = {
+	[KeyType in keyof T]: T[KeyType];
+} & {};
+/**
+Returns the last element of a union type.
+
+@example
+```
+type Last = LastOfUnion<1 | 2 | 3>;
+//=> 3
+```
+*/
+export type LastOfUnion<T> = UnionToIntersection<T extends any ? () => T : never> extends () => (infer R) ? R : never;
+/**
+Convert a union type into an unordered tuple type of its elements.
+
+"Unordered" means the elements of the tuple are not guaranteed to be in the same order as in the union type. The arrangement can appear random and may change at any time.
+
+This can be useful when you have objects with a finite set of keys and want a type defining only the allowed keys, but do not want to repeat yourself.
+
+@example
+```
+import type {UnionToTuple} from 'type-fest';
+
+type Numbers = 1 | 2 | 3;
+type NumbersTuple = UnionToTuple<Numbers>;
+//=> [1, 2, 3]
+```
+
+@example
+```
+import type {UnionToTuple} from 'type-fest';
+
+const pets = {
+  dog: '🐶',
+  cat: '🐱',
+  snake: '🐍',
+};
+
+type Pet = keyof typeof pets;
+//=> 'dog' | 'cat' | 'snake'
+
+const petList = Object.keys(pets) as UnionToTuple<Pet>;
+//=> ['dog', 'cat', 'snake']
+```
+
+@category Array
+*/
+export type UnionToTuple<T, L = LastOfUnion<T>> = IsNever<T> extends false ? [
+	...UnionToTuple<Exclude<T, L>>,
+	L
+] : [
+];
+export type GetKey<Value> = {
+	[Key in keyof Values]: Value extends Values[Key] ? Key : never;
+}[keyof Values];
+export type GetTypes<Value extends unknown[]> = Value extends [
+	infer Single
+] ? Single : Value;
+export type GetType<Value> = GetTypes<UnionToTuple<GetKey<Value>>>;
+export type InferProperty<Value> = Value extends Property ? Value["type"] extends keyof Values ? Values[Value["type"]] : Value["type"] extends (keyof Values)[] ? Values[Value["type"][number]] : never : never;
+export type InferValue<Value> = Value extends keyof Values ? Values[Value] : Value extends (keyof Values)[] ? Values[Value[number]] : never;
+export type Inferred<Model extends Schema> = {
+	[Key in InferredRequiredProperties<Model>]: Model[Key] extends Property ? InferProperty<Model[Key]> : InferValue<Model[Key]>;
+} & {
+	[Key in InferredOptionalProperties<Model>]?: Model[Key] extends Property ? InferProperty<Model[Key]> : never;
+};
+export type InferredOptionalProperties<Model extends Schema> = {
+	[Key in keyof Model]: Model[Key] extends Property ? Model[Key]["required"] extends false ? Key : never : never;
+}[keyof Model];
+export type InferredRequiredProperties<Model extends Schema> = {
+	[Key in keyof Model]: Model[Key] extends Property ? Model[Key]["required"] extends false ? never : Key : Key;
+}[keyof Model];
+export type OptionalProperty<Type> = {
+	required: false;
+	type: GetType<Type>;
+};
+export type Property = {
+	required?: boolean;
+	type: keyof Values | (keyof Values)[];
+};
+export type RequiredProperty<Type> = {
+	required: true;
+	type: GetType<Type>;
+};
+/**
+ * A schema for validating objects
+ */
+export type Schema = Record<string, keyof Values | (keyof Values)[] | Property>;
+/**
+ * A schematic for validating objects
+ */
+export type Schematic<Model> = {
+	/**
+	 * Does the value match the schema?
+	 */
+	is(value: unknown): value is Model;
+};
+export type Typed = Record<string, unknown>;
+/**
+ * A typed schema for validating objects
+ */
+export type TypedSchema<Model extends Typed> = Simplify<{
+	[Key in RequiredKeysOf<Model>]: GetType<Model[Key]> | RequiredProperty<Model[Key]>;
+} & {
+	[Key in OptionalKeysOf<Model>]: OptionalProperty<Model[Key]>;
+}>;
+export type ValidatedProperty = {
+	required: boolean;
+	types: (keyof Values)[];
+};
+export type ValidatedSchema = {
+	keys: string[];
+	length: number;
+	properties: Record<string, ValidatedProperty>;
+};
+export type Values = {
+	array: unknown[];
+	bigint: bigint;
+	boolean: boolean;
+	date: Date;
+	function: Function;
+	null: null;
+	number: number;
+	object: object;
+	string: string;
+	symbol: symbol;
+	undefined: undefined;
+};
+
+export {};