@oscarpalmer/jhunal 0.24.0 → 0.26.0

package/src/constants.ts

@@ -23,9 +23,9 @@ export const MESSAGE_CONSTRUCTOR = 'Expected a constructor function';
 
 // #region Names
 
-export const NAME_SCHEMATIC = 'Schematic';
+export const NAME_SCHEMA = 'Schema';
 
-export const NAME_SCHEMATIC_PREFIXED = 'a Schematic';
+export const NAME_SCHEMA_PREFIXED = 'a Schema';
 
 export const NAME_ERROR_SCHEMATIC = 'SchematicError';
 
@@ -39,7 +39,7 @@ export const PROPERTY_DEFAULT = '$default';
 
 export const PROPERTY_REQUIRED = '$required';
 
-export const PROPERTY_SCHEMATIC = '$schematic';
+export const PROPERTY_SCHEMA = '$schema';
 
 export const PROPERTY_TYPE = '$type';
 

package/src/helpers/misc.helper.ts

@@ -2,7 +2,7 @@ import {isConstructor, isPlainObject} from '@oscarpalmer/atoms/is';
 import type {Constructor} from '@oscarpalmer/atoms/models';
 import {
 	MESSAGE_CONSTRUCTOR,
-	PROPERTY_SCHEMATIC,
+	PROPERTY_SCHEMA,
 	REPORTING_ALL,
 	REPORTING_FIRST,
 	REPORTING_NONE,
@@ -14,7 +14,7 @@ import type {
 	ReportingType,
 	ValidatorParameters,
 } from '../models/validation.model';
-import type {Schematic} from '../schematic';
+import type {Schema} from '../schema';
 
 export function getParameters(input?: unknown): ValidatorParameters {
 	if (typeof input === 'boolean') {
@@ -82,11 +82,11 @@ export function instanceOf<Instance>(
  * @param value Value to check
  * @returns `true` if the value is a schematic, `false` otherwise
  */
-export function isSchematic(value: unknown): value is Schematic<never> {
+export function isSchema(value: unknown): value is Schema<never> {
 	return (
 		typeof value === 'object' &&
 		value !== null &&
-		PROPERTY_SCHEMATIC in value &&
-		value[PROPERTY_SCHEMATIC] === true
+		PROPERTY_SCHEMA in value &&
+		value[PROPERTY_SCHEMA] === true
 	);
 }

package/src/index.ts

@@ -1,10 +1,10 @@
-export {instanceOf, isSchematic} from './helpers/misc.helper';
-export type {Schema} from './models/schema.plain.model';
-export type {TypedSchema} from './models/schema.typed.model';
+export {instanceOf, isSchema} from './helpers/misc.helper';
+export type {Schematic} from './models/schematic.plain.model';
+export type {TypedSchematic} from './models/schematic.typed.model';
 export {
 	SchematicError,
 	ValidationError,
 	type GetOptions,
 	type IsOptions,
 } from './models/validation.model';
-export {schematic, type Schematic} from './schematic';
+export {schema, type Schema} from './schema';

package/src/models/infer.model.ts

@@ -1,26 +1,26 @@
 import type {Constructor, Simplify} from '@oscarpalmer/atoms/models';
-import type {Schematic} from '../schematic';
+import type {Schema} from '../schema';
 import type {IsOptionalProperty, ValueName, Values} from './misc.model';
-import type {PlainSchema, Schema, SchemaProperty} from './schema.plain.model';
+import type {PlainSchematic, Schematic, SchematicProperty} from './schematic.plain.model';
 
 /**
- * Infers the TypeScript type from a {@link Schema} definition
+ * Infers the TypeScript type from a {@link Schematic} definition
  *
- * @template Model Schema to infer types from
+ * @template Model Schematic to infer types from
  *
  * @example
  * ```ts
- * const userSchema = {
+ * const userSchematic = {
  *   name: 'string',
  *   age: 'number',
  *   address: { $required: false, $type: 'string' },
- * } satisfies Schema;
+ * } satisfies Schematic;
  *
- * type User = Infer<typeof userSchema>;
+ * type User = Infer<typeof userSchematic>;
  * // { name: string; age: number; address?: string }
  * ```
  */
-export type Infer<Model extends Schema> = Simplify<
+export type Infer<Model extends Schematic> = Simplify<
 	{
 		[Key in InferRequiredKeys<Model>]: InferSchemaEntry<Model[Key]>;
 	} & {
@@ -29,16 +29,16 @@ export type Infer<Model extends Schema> = Simplify<
 >;
 
 /**
- * Extracts keys from a {@link Schema} whose entries are optional _(i.e., `$required` is `false`)_
+ * Extracts keys from a {@link Schematic} whose entries are optional _(i.e., `$required` is `false`)_
  *
- * @template Model - {@link Schema} to extract optional keys from
+ * @template Model - {@link Schematic} to extract optional keys from
  */
-export type InferOptionalKeys<Model extends Schema> = keyof {
+export type InferOptionalKeys<Model extends Schematic> = keyof {
 	[Key in keyof Model as IsOptionalProperty<Model[Key]> extends true ? Key : never]: never;
 };
 
 /**
- * Infers the TypeScript type from a {@link SchemaProperty}'s `$type` field
+ * Infers the TypeScript type from a {@link SchematicProperty}'s `$type` field
  *
  * @template Value `$type` value _(single or array)_
  */
@@ -49,34 +49,34 @@ export type InferPropertyType<Value> = Value extends (infer Item)[]
 /**
  * Maps a single `$type` definition to its TypeScript equivalent
  *
- * Resolves, in order: {@link Constructor} instances, {@link Schematic} models, {@link ValueName} strings, and nested {@link PlainSchema} objects
+ * Resolves, in order: {@link Constructor}s, {@link Schema} instances, {@link ValueName} values, and nested {@link PlainSchematic} objects
  *
  * @template Value single type definition
  */
 export type InferPropertyValue<Value> =
 	Value extends Constructor<infer Instance>
 		? Instance
-		: Value extends Schematic<infer Model>
+		: Value extends Schema<infer Model>
 			? Model
 			: Value extends ValueName
 				? Values[Value & ValueName]
-				: Value extends Schema
+				: Value extends PlainSchematic
 					? Infer<Value>
 					: never;
 
 /**
- * Extracts keys from a {@link Schema} whose entries are required _(i.e., `$required` is not `false`)_
+ * Extracts keys from a {@link Schematic} whose entries are required _(i.e., `$required` is not `false`)_
  *
- * @template Model Schema to extract required keys from
+ * @template Model Schematic to extract required keys from
  */
-export type InferRequiredKeys<Model extends Schema> = keyof {
+export type InferRequiredKeys<Model extends Schematic> = keyof {
 	[Key in keyof Model as IsOptionalProperty<Model[Key]> extends true ? never : Key]: never;
 };
 
 /**
- * Infers the TypeScript type from a top-level {@link Schema} entry
+ * Infers the TypeScript type from a top-level {@link Schematic} entry
  *
- * @template Value Schema entry value _(single or array)_
+ * @template Value Schematic entry value _(single or array)_
  */
 export type InferSchemaEntry<Value> = Value extends (infer Item)[]
 	? InferSchemaEntryValue<Item>
@@ -85,21 +85,19 @@ export type InferSchemaEntry<Value> = Value extends (infer Item)[]
 /**
  * Maps a single top-level schema entry to its TypeScript type
  *
- * Resolves, in order: {@link Constructor} instances, {@link Schematic} models, {@link SchemaProperty} objects, {@link PlainSchema} objects, and {@link ValueName} strings
+ * Resolves, in order: {@link Constructor}s, {@link Schema} instances, {@link SchemaProperty} objects, {@link PlainSchematic} objects, and {@link ValueName} values
  *
  * @template Value single schema entry
  */
 export type InferSchemaEntryValue<Value> =
 	Value extends Constructor<infer Instance>
 		? Instance
-		: Value extends Schematic<infer Model>
+		: Value extends Schema<infer Model>
 			? Model
-			: Value extends SchemaProperty
+			: Value extends SchematicProperty
 				? InferPropertyType<Value['$type']>
-				: Value extends PlainSchema
-					? Infer<Value & Schema>
+				: Value extends PlainSchematic
+					? Infer<Value & Schematic>
 					: Value extends ValueName
 						? Values[Value & ValueName]
-						: Value extends Schema
-							? Infer<Value>
-							: never;
+						: never;

package/src/models/misc.model.ts

@@ -1,4 +1,4 @@
-import type {SchemaProperty} from './schema.plain.model';
+import type {SchematicProperty} from './schematic.plain.model';
 
 /**
  * Removes duplicate types from a tuple, preserving first occurrence order
@@ -43,11 +43,11 @@ export type ExtractValueNames<Value> = Value extends ValueName
 /**
  * Determines whether a schema entry is optional
  *
- * Returns `true` if the entry is a {@link SchemaProperty} with `$required` set to `false`; otherwise returns `false`
+ * Returns `true` if the entry is a {@link SchematicProperty} with `$required` set to `false`; otherwise returns `false`
  *
  * @template Value Schema entry to check
  */
-export type IsOptionalProperty<Value> = Value extends SchemaProperty
+export type IsOptionalProperty<Value> = Value extends SchematicProperty
 	? Value['$required'] extends false
 		? true
 		: false

package/src/models/{schema.plain.model.ts → schematic.plain.model.ts}

@@ -1,12 +1,12 @@
 import type {Constructor} from '@oscarpalmer/atoms/models';
-import type {Schematic} from '../schematic';
+import type {Schema} from '../schema';
 import type {ExtractValueNames, ValueName, Values} from './misc.model';
 
 /**
- * A generic schema allowing nested schemas, {@link SchemaEntry} values, or arrays of {@link SchemaEntry} as values
+ * A generic schematic allowing nested schematics, {@link SchematicEntry} values, or arrays of {@link SchematicEntry} as values
  */
-export type PlainSchema = {
-	[key: string]: PlainSchema | SchemaEntry | SchemaEntry[] | undefined;
+export type PlainSchematic = {
+	[key: string]: PlainSchematic | SchematicEntry | SchematicEntry[] | undefined;
 } & {
 	$default?: never;
 	$required?: never;
@@ -15,29 +15,29 @@ export type PlainSchema = {
 };
 
 /**
- * A schema for validating objects
+ * A schematic for validating objects
  *
  * @example
  * ```ts
- * const schema: Schema = {
+ * const schematic = {
  *   name: 'string',
  *   age: 'number',
  *   tags: ['string', 'number'],
- * };
+ * } satisfies Schematic;
  * ```
  */
-export type Schema = PlainSchema;
+export type Schematic = PlainSchematic;
 
 /**
- * A union of all valid types for a single schema entry
+ * A union of all valid types for a single schematic entry
  *
- * Can be a {@link Constructor}, {@link PlainSchema}, {@link SchemaProperty}, {@link Schematic}, {@link ValueName} string, or a custom validator function
+ * Can be a {@link Constructor}, {@link PlainSchematic}, {@link SchematicProperty}, {@link Schema}, {@link ValueName}, or a custom validator function
  */
-export type SchemaEntry =
+export type SchematicEntry =
 	| Constructor
-	| PlainSchema
-	| SchemaProperty
-	| Schematic<unknown>
+	| PlainSchematic
+	| Schema<unknown>
+	| SchematicProperty
 	| ValueName
 	| ((value: unknown) => boolean);
 
@@ -46,7 +46,7 @@ export type SchemaEntry =
  *
  * @example
  * ```ts
- * const prop: SchemaProperty = {
+ * const prop: SchematicProperty = {
  *   $required: false,
  *   $type: ['string', 'number'],
  *   $validators: {
@@ -56,7 +56,7 @@ export type SchemaEntry =
  * };
  * ```
  */
-export type SchemaProperty = {
+export type SchematicProperty = {
 	$default?: unknown;
 	/**
 	 * Whether the property is required _(defaults to `true`)_
@@ -73,14 +73,14 @@ export type SchemaProperty = {
 };
 
 /**
- * A union of valid types for a {@link SchemaProperty}'s `$type` field
+ * A union of valid types for a {@link SchematicProperty}'s `$type` field
  *
- * Can be a {@link Constructor}, {@link PlainSchema}, {@link Schematic}, {@link ValueName} string, or a custom validator function
+ * Can be a {@link Constructor}, {@link PlainSchematic}, {@link Schema}, {@link ValueName} string, or a custom validator function
  */
 export type SchemaPropertyType =
 	| Constructor
-	| PlainSchema
-	| Schematic<unknown>
+	| PlainSchematic
+	| Schema<unknown>
 	| ValueName
 	| ((value: unknown) => boolean);
 

package/src/models/{schema.typed.model.ts → schematic.typed.model.ts}

@@ -1,11 +1,11 @@
 import type {PlainObject, Simplify} from '@oscarpalmer/atoms/models';
-import type {Schematic} from '../schematic';
+import type {Schema} from '../schema';
 import type {OptionalKeys, RequiredKeys} from './misc.model';
-import type {PropertyValidators} from './schema.plain.model';
+import type {PropertyValidators} from './schematic.plain.model';
 import type {ToSchemaPropertyType, ToSchemaType} from './transform.model';
 
 /**
- * A typed optional property definition generated by {@link TypedSchema} for optional keys, with `$required` set to `false` and excludes `undefined` from the type
+ * A typed optional property definition generated by {@link TypedSchematic} for optional keys, with `$required` set to `false` and excludes `undefined` from the type
  *
  * @template Value Property's type _(including `undefined`)_
  *
@@ -24,7 +24,7 @@ export type TypedPropertyOptional<Value> = {
 };
 
 /**
- * A typed required property definition generated by {@link TypedSchema} for required keys, with `$required` defaulting to `true`
+ * A typed required property definition generated by {@link TypedSchematic} for required keys, with `$required` defaulting to `true`
  *
  * @template Value Property's type
  *
@@ -45,7 +45,7 @@ export type TypedPropertyRequired<Value> = {
 /**
  * Creates a schema type constrained to match a TypeScript type
  *
- * Required keys map to {@link ToSchemaType} or {@link TypedPropertyRequired}; plain object values may also use {@link Schematic}. Optional keys map to {@link TypedPropertyOptional} or, for plain objects, {@link TypedSchemaOptional}
+ * Required keys map to {@link ToSchemaType} or {@link TypedPropertyRequired}; plain object values may also use {@link Schema}
  *
  * @template Model Object type to generate a schema for
  *
@@ -60,14 +60,14 @@ export type TypedPropertyRequired<Value> = {
  * };
  * ```
  */
-export type TypedSchema<Model extends PlainObject> = Simplify<
+export type TypedSchematic<Model extends PlainObject> = Simplify<
 	{
 		[Key in RequiredKeys<Model>]: Model[Key] extends PlainObject
-			? Schematic<Model[Key]>
+			? Schema<Model[Key]>
 			: ToSchemaType<Model[Key]> | TypedPropertyRequired<Model[Key]>;
 	} & {
 		[Key in OptionalKeys<Model>]: Exclude<Model[Key], undefined> extends PlainObject
-			? Schematic<Exclude<Model[Key], undefined>>
+			? Schema<Exclude<Model[Key], undefined>>
 			: TypedPropertyOptional<Model[Key]>;
 	}
 >;

package/src/models/transform.model.ts

@@ -1,7 +1,7 @@
 import type {PlainObject} from '@oscarpalmer/atoms/models';
-import type {Schematic} from '../schematic';
+import type {Schema} from '../schema';
 import type {DeduplicateTuple, UnionToTuple, UnwrapSingle, Values} from './misc.model';
-import type {TypedSchema} from './schema.typed.model';
+import type {TypedSchematic} from './schematic.typed.model';
 
 /**
  * Maps each element of a tuple through {@link ToValueType}
@@ -36,12 +36,12 @@ export type ToSchemaPropertyType<Value> = UnwrapSingle<
 /**
  * Converts a single type to its schema property equivalent
  *
- * Plain objects become {@link TypedSchema}; primitives go through {@link ToValueType}
+ * Plain objects become {@link TypedSchematic}; primitives go through {@link ToValueType}
  *
  * @template Value Type to convert
  */
 export type ToSchemaPropertyTypeEach<Value> = Value extends PlainObject
-	? TypedSchema<Value>
+	? TypedSchematic<Value>
 	: ToValueType<Value>;
 
 /**
@@ -56,7 +56,7 @@ export type ToSchemaType<Value> = UnwrapSingle<
 /**
  * Maps a type to its {@link ValueName} string equivalent
  *
- * Resolves {@link Schematic} types as-is, then performs a reverse-lookup against {@link Values} _(excluding `'object'`)_ to find a matching key. If no match is found, `object` types resolve to `'object'` or a type-guard function, and all other unrecognised types resolve to a type-guard function
+ * Resolves {@link Schema} types as-is, then performs a reverse-lookup against {@link Values} _(excluding `'object'`)_ to find a matching key. If no match is found, `object` types resolve to `'object'` or a type-guard function, and all other unrecognised types resolve to a type-guard function
  *
  * @template Value Type to map
  *
@@ -68,7 +68,7 @@ export type ToSchemaType<Value> = UnwrapSingle<
  * ```
  */
 export type ToValueType<Value> =
-	Value extends Schematic<any>
+	Value extends Schema<any>
 		? Value
 		: {
 					[Key in keyof Omit<Values, 'object'>]: Value extends Values[Key] ? Key : never;

package/src/models/validation.model.ts

@@ -1,7 +1,7 @@
 import type {GenericCallback, PlainObject} from '@oscarpalmer/atoms/models';
 import {join} from '@oscarpalmer/atoms/string';
 import {NAME_ERROR_SCHEMATIC, NAME_ERROR_VALIDATION} from '../constants';
-import type {Schematic} from '../schematic';
+import type {Schema} from '../schema';
 import type {ValueName} from './misc.model';
 
 // #region Named validation
@@ -147,6 +147,6 @@ export type ValidatorParameters = {
 	strict: boolean;
 };
 
-export type ValidatorType = Function | PlainObject | Schematic<unknown> | ValueName;
+export type ValidatorType = Function | PlainObject | Schema<unknown> | ValueName;
 
 // #endregion

package/src/{schematic.ts → schema.ts}

@@ -2,11 +2,11 @@ import {isPlainObject} from '@oscarpalmer/atoms/is';
 import type {PlainObject} from '@oscarpalmer/atoms/models';
 import {error, ok} from '@oscarpalmer/atoms/result/misc';
 import type {Result} from '@oscarpalmer/atoms/result/models';
-import {PROPERTY_SCHEMATIC, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE} from './constants';
-import {getParameters, isSchematic} from './helpers/misc.helper';
+import {PROPERTY_SCHEMA, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE} from './constants';
+import {getParameters, isSchema} from './helpers/misc.helper';
 import type {Infer} from './models/infer.model';
-import type {Schema} from './models/schema.plain.model';
-import type {TypedSchema} from './models/schema.typed.model';
+import type {Schematic} from './models/schematic.plain.model';
+import type {TypedSchematic} from './models/schematic.typed.model';
 import {
 	SchematicError,
 	type GetOptions,
@@ -17,21 +17,21 @@ import {
 import {getObjectValidator} from './validator/object.validator';
 
 /**
- * A schematic for validating objects
+ * A schema for validating objects
  */
-export class Schematic<Model> {
-	declare private readonly $schematic: true;
+export class Schema<Model> {
+	declare private readonly $schema: true;
 
 	#validator: Validator;
 
 	constructor(validator: Validator) {
-		Object.defineProperty(this, PROPERTY_SCHEMATIC, {
+		Object.defineProperty(this, PROPERTY_SCHEMA, {
 			value: true,
 		});
 
 		this.#validator = validator;
 
-		schematicValidator.set(this, validator);
+		schemaValidators.set(this, validator);
 	}
 
 	/**
@@ -102,7 +102,7 @@ export class Schematic<Model> {
 	 * @param options Validation options
 	 * @returns Deeply cloned value, or `undefined` if it's invalid
 	 */
-	get(value: unknown, options: GetOptions<'none'>): Model | undefined;
+	get(value: unknown, options: Partial<GetOptions<'none'>>): Model | undefined;
 
 	/**
 	 * Parse a value according to the schema
@@ -121,8 +121,10 @@ export class Schematic<Model> {
 
 		if (result === true) {
 			return parameters.reporting.none || parameters.reporting.throw
-				? parameters.output
-				: ok(parameters.output);
+				? parameters.clone
+					? parameters.output
+					: value
+				: ok(parameters.clone ? parameters.output : value);
 		}
 
 		if (parameters.reporting.none) {
@@ -200,7 +202,7 @@ export class Schematic<Model> {
 	 * @param options Validation options
 	 * @returns `true` if the value matches the schema, otherwise `false`
 	 */
-	is(value: unknown, options: IsOptions<'none'>): value is Model;
+	is(value: unknown, options: Partial<IsOptions<'none'>>): value is Model;
 
 	/**
 	 * Does the value match the schema?
@@ -230,25 +232,25 @@ export class Schematic<Model> {
 }
 
 /**
- * Create a schematic from a schema
+ * Create a schema from a schematic
  * @template Model Schema type
- * @param schema Schema to create the schematic from
- * @throws Throws {@link SchematicError} if the schema can not be converted into a schematic
- * @returns A schematic for the given schema
+ * @param schema Schematic to create the schema from
+ * @throws Throws {@link SchematicError} if the schematic can not be converted into a schema
+ * @returns A schema for the given schematic
  */
-export function schematic<Model extends Schema>(schema: Model): Schematic<Infer<Model>>;
+export function schema<Model extends Schematic>(schema: Model): Schema<Infer<Model>>;
 
 /**
- * Create a schematic from a typed schema
+ * Create a schema from a typed schematic
  * @template Model Existing type
- * @param schema Typed schema to create the schematic from
- * @throws Throws {@link SchematicError} if the schema can not be converted into a schematic
- * @returns A schematic for the given typed schema
+ * @param schema Typed schematic to create the schema from
+ * @throws Throws {@link SchematicError} if the schematic can not be converted into a schema
+ * @returns A schema for the given typed schematic
  */
-export function schematic<Model extends PlainObject>(schema: TypedSchema<Model>): Schematic<Model>;
+export function schema<Model extends PlainObject>(schema: TypedSchematic<Model>): Schema<Model>;
 
-export function schematic<Model extends Schema>(schema: Model): Schematic<Model> {
-	if (isSchematic(schema)) {
+export function schema<Model extends Schematic>(schema: Model): Schema<Model> {
+	if (isSchema(schema)) {
 		return schema;
 	}
 
@@ -256,7 +258,7 @@ export function schematic<Model extends Schema>(schema: Model): Schematic<Model>
 		throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE);
 	}
 
-	return new Schematic<Model>(getObjectValidator(schema));
+	return new Schema<Model>(getObjectValidator(schema));
 }
 
-export const schematicValidator = new WeakMap<Schematic<unknown>, Validator>();
+export const schemaValidators = new WeakMap<Schema<unknown>, Validator>();