@tstdl/base 0.91.52 → 0.92.0

package/schema/schemas/object.js

@@ -6,7 +6,7 @@ import { memoizeSingle } from '../../utils/function/memoize.js';
 import { filterObject, fromEntries, mapObjectValues, objectKeys } from '../../utils/object/object.js';
 import { assert, isArray, isDefined, isFunction, isLiteralObject, isNotNull, isNotNullOrUndefined, isNull, isObject, isUndefined } from '../../utils/type-guards.js';
 import { typeOf } from '../../utils/type-of.js';
-import { Class, Property } from '../decorators/index.js';
+import { Class, PropertySchema } from '../decorators/index.js';
 import { Schema } from '../schema.js';
 import { schemaTestableToSchema } from '../testable.js';
 import { array } from './array.js';
@@ -23,7 +23,7 @@ export class ObjectSchema extends Schema {
     unknownPropertiesKey;
     factory;
     constructor(properties, options = {}) {
-        super();
+        super(options);
         this.properties = mapObjectValues(properties, (value) => schemaTestableToSchema(value));
         this.mask = options.mask ?? null;
         this.unknownProperties = isNotNullOrUndefined(options.unknownProperties) ? schemaTestableToSchema(options.unknownProperties) : null;
@@ -92,7 +92,8 @@ export function assign(...schemasOrTypes) {
         name: schemas.at(-1)?.name,
         mask: schemas.findLast((schema) => isNotNull(schema.mask))?.mask,
         unknownProperties: schemas.findLast((schema) => isNotNull(schema.unknownProperties))?.unknownProperties,
-        unknownPropertiesKey: schemas.findLast((schema) => isNotNull(schema.unknownPropertiesKey))?.unknownPropertiesKey
+        unknownPropertiesKey: schemas.findLast((schema) => isNotNull(schema.unknownPropertiesKey))?.unknownPropertiesKey,
+        description: schemas.findLast((schema) => isNotNull(schema.description))?.description
     });
 }
 export function partial(schemaOrType, keyOrKeys) {
@@ -149,13 +150,17 @@ function _tryGetSchemaFromReflection(type) {
         factory: isDefined(typeData.factory) ? typeData.factory : { type: type },
         mask: typeData.mask,
         unknownProperties: typeData.unknownProperties,
-        unknownPropertiesKey: typeData.unknownPropertiesKey
+        unknownPropertiesKey: typeData.unknownPropertiesKey,
+        description: typeData.description,
+        example: typeData.example
     });
     const prototype = Reflect.getPrototypeOf(type);
     if (isNotNull(prototype) && reflectionRegistry.hasType(prototype)) {
         const parentSchema = getSchemaFromReflection(prototype);
         assert(parentSchema instanceof ObjectSchema, 'Can not infer an ObjectSchema from reflection when parent class has an explicit non-object schema defined.');
-        return assign(parentSchema, schema);
+        const extendedSchema = assign(parentSchema, schema);
+        extendedSchema.factory = schema.factory;
+        return extendedSchema;
     }
     return schema;
 }
@@ -166,7 +171,7 @@ function getObjectSchemaPropertiesFromReflection(metadata, type) {
         if (isUndefined(reflectionData?.schema) && (propertyMetadata.type == Object)) {
             throw new Error(`Schema of property "${String(key)}" on type ${type.name} is inferred as Object. This is most likely unwanted and happens if the property is defined as partial or the type is an union. Use an explicit @Property(Object) if this is wanted.`);
         }
-        let propertySchema = reflectionData?.schema ?? propertyMetadata.type;
+        let propertySchema = isDefined(reflectionData?.schema) ? reflectionData.schema(reflectionData) : propertyMetadata.type;
         if (isUndefined(propertySchema)) {
             throw new Error(`Could not infer schema for property "${String(key)}" on type ${type.name}. This happens if neither explicit @Property(type) is used nor reflection metadata is available.`);
         }
@@ -199,7 +204,7 @@ export function Record(key, value, options) {
         if (data.type == 'class') {
             return Class({ unknownPropertiesKey: keySchema, unknownProperties: valueSchema })(args[0]);
         }
-        return Property(record(keySchema, valueSchema, options), options)(args[0], args[1], args[2]);
+        return PropertySchema((reflectionData) => record(keySchema, valueSchema, { description: reflectionData.description, example: reflectionData.example, ...options }), options)(args[0], args[1], args[2]);
     });
 }
 export const emptyObjectSchema = explicitObject({});

package/schema/schemas/one-or-many.d.ts

@@ -1,13 +1,14 @@
 import type { JsonPath } from '../../json-path/json-path.js';
 import type { OneOrMany as OneOrManyType } from '../../types.js';
 import { type SchemaPropertyDecorator, type SchemaPropertyDecoratorOptions } from '../decorators/index.js';
-import { Schema, type SchemaTestable, type SchemaTestOptions, type SchemaTestResult } from '../schema.js';
+import { Schema, type SchemaOptions, type SchemaTestable, type SchemaTestOptions, type SchemaTestResult } from '../schema.js';
+export type OneOrManySchemaOptions<T> = SchemaOptions<T | T[]>;
 export type OneOrMany<T> = OneOrManyType<T>;
 export declare class OneOrManySchema<T> extends Schema<T | T[]> {
     readonly name: string;
     readonly schema: Schema<T | T[]>;
-    constructor(schema: SchemaTestable<T>);
+    constructor(schema: SchemaTestable<T>, options?: OneOrManySchemaOptions<T>);
     _test(value: any, path: JsonPath, options: SchemaTestOptions): SchemaTestResult<T | T[]>;
 }
-export declare function oneOrMany<T>(schema: SchemaTestable<T>): OneOrManySchema<T>;
-export declare function OneOrMany(schema: SchemaTestable, options?: SchemaPropertyDecoratorOptions): SchemaPropertyDecorator;
+export declare function oneOrMany<T>(schema: SchemaTestable<T>, options?: OneOrManySchemaOptions<T>): OneOrManySchema<T>;
+export declare function OneOrMany<T>(schema: SchemaTestable<T>, options?: OneOrManySchemaOptions<T> & SchemaPropertyDecoratorOptions): SchemaPropertyDecorator;

package/schema/schemas/one-or-many.js

@@ -1,5 +1,5 @@
 import { lazyProperty } from '../../utils/object/lazy-property.js';
-import { Property } from '../decorators/index.js';
+import { PropertySchema } from '../decorators/index.js';
 import { Schema } from '../schema.js';
 import { schemaTestableToSchema } from '../testable.js';
 import { array } from './array.js';
@@ -7,8 +7,8 @@ import { union } from './union.js';
 export class OneOrManySchema extends Schema {
     name;
     schema;
-    constructor(schema) {
-        super();
+    constructor(schema, options) {
+        super(options);
         const oneSchema = schemaTestableToSchema(schema);
         this.schema = union(oneSchema, array(oneSchema));
         lazyProperty(this, 'name', () => `OneOrMany[${oneSchema.name}]`);
@@ -17,9 +17,9 @@ export class OneOrManySchema extends Schema {
         return this.schema._test(value, path, options);
     }
 }
-export function oneOrMany(schema) {
-    return new OneOrManySchema(schema);
+export function oneOrMany(schema, options) {
+    return new OneOrManySchema(schema, options);
 }
 export function OneOrMany(schema, options) {
-    return Property(oneOrMany(schema), options);
+    return PropertySchema((data) => oneOrMany(schema, { description: data.description, example: data.example, ...options }), options);
 }

package/schema/schemas/optional.d.ts

@@ -10,4 +10,4 @@ export declare class OptionalSchema<T> extends Schema<T | undefined> {
     _test(value: any, path: JsonPath, options: SchemaTestOptions): SchemaTestResult<T | undefined>;
 }
 export declare function optional<T>(schema: SchemaTestable<T>): OptionalSchema<T>;
-export declare function Optional(schema?: SchemaTestable, options?: TypedOmit<SchemaPropertyDecoratorOptions, 'optional'>): SchemaPropertyDecorator;
+export declare function Optional<T>(schema?: SchemaTestable<T>, options?: TypedOmit<SchemaPropertyDecoratorOptions, 'optional'>): SchemaPropertyDecorator;

package/schema/schemas/optional.js

@@ -25,5 +25,5 @@ export function optional(schema) {
     return new OptionalSchema(schema);
 }
 export function Optional(schema, options) {
-    return createSchemaPropertyDecorator({ schema, ...options, optional: true });
+    return createSchemaPropertyDecorator({ schema: () => schema, ...options, optional: true });
 }

package/schema/schemas/readable-stream.d.ts

@@ -1,6 +1,6 @@
 import { type SchemaPropertyDecorator, type SchemaPropertyDecoratorOptions } from '../decorators/index.js';
 import { SimpleSchema, type SimpleSchemaOptions } from './simple.js';
-export type ReadableStreamSchemaOptions = SimpleSchemaOptions;
+export type ReadableStreamSchemaOptions = SimpleSchemaOptions<ReadableStream>;
 export declare class ReadableStreamSchema extends SimpleSchema<ReadableStream> {
     readonly name = "ReadableStream";
     constructor(options?: ReadableStreamSchemaOptions);

package/schema/schemas/readable-stream.js

@@ -1,5 +1,5 @@
 import { isReadableStream } from '../../utils/type-guards.js';
-import { Property } from '../decorators/index.js';
+import { PropertySchema } from '../decorators/index.js';
 import { SimpleSchema } from './simple.js';
 export class ReadableStreamSchema extends SimpleSchema {
     name = 'ReadableStream';
@@ -11,5 +11,5 @@ export function readableStream(options) {
     return new ReadableStreamSchema(options);
 }
 export function ReadableStreamProperty(options) {
-    return Property(readableStream(options), options);
+    return PropertySchema((data) => readableStream({ description: data.description, example: data.example, ...options }), options);
 }

package/schema/schemas/regexp.d.ts

@@ -1,6 +1,6 @@
 import { type SchemaPropertyDecorator, type SchemaPropertyDecoratorOptions } from '../decorators/index.js';
 import { SimpleSchema, type SimpleSchemaOptions } from './simple.js';
-export type RegExpSchemaOptions = SimpleSchemaOptions;
+export type RegExpSchemaOptions = SimpleSchemaOptions<RegExp>;
 export declare class RegExpSchema extends SimpleSchema<RegExp> {
     readonly name = "RegExp";
     constructor(options?: RegExpSchemaOptions);

package/schema/schemas/regexp.js

@@ -1,5 +1,5 @@
 import { isRegExp } from '../../utils/type-guards.js';
-import { Property } from '../decorators/index.js';
+import { PropertySchema } from '../decorators/index.js';
 import { SchemaError } from '../schema.error.js';
 import { SimpleSchema } from './simple.js';
 export class RegExpSchema extends SimpleSchema {
@@ -24,5 +24,5 @@ export function regExp(options) {
     return new RegExpSchema(options);
 }
 export function RegExpProperty(options) {
-    return Property(regExp(options), options);
+    return PropertySchema((data) => regExp({ description: data.description, example: data.example, ...options }), options);
 }

package/schema/schemas/simple.d.ts

@@ -1,8 +1,8 @@
 import type { JsonPath } from '../../json-path/json-path.js';
 import type { AbstractConstructor, OneOrMany } from '../../types.js';
-import { Schema, type SchemaTestOptions, type SchemaTestResult } from '../schema.js';
+import { Schema, type SchemaOptions, type SchemaTestOptions, type SchemaTestResult } from '../schema.js';
 import type { CoerceResult, Coercible, ConstraintResult } from '../types.js';
-export type SimpleSchemaOptions = Coercible;
+export type SimpleSchemaOptions<T> = SchemaOptions<T> & Coercible;
 type SimpleSchemaRefinements<T> = {
     coercers?: SimpleSchemaCoercers<T>;
     constraints?: (SimpleSchemaConstraint<T> | null)[];
@@ -21,7 +21,7 @@ export type SimpleSchemaConstraint<T> = (value: T) => ConstraintResult;
 export type SimpleSchemaGotValueFormatter = (value: unknown) => string;
 export declare abstract class SimpleSchema<T> extends Schema<T> {
     #private;
-    constructor(expected: OneOrMany<string | AbstractConstructor>, guardFn: (value: any) => value is T, options?: SimpleSchemaOptions, refinements?: SimpleSchemaRefinements<T>);
+    constructor(expected: OneOrMany<string | AbstractConstructor>, guardFn: (value: any) => value is T, options?: SimpleSchemaOptions<T>, refinements?: SimpleSchemaRefinements<T>);
     _test(value: any, path: JsonPath, options: SchemaTestOptions): SchemaTestResult<T>;
 }
 export {};

package/schema/schemas/simple.js

@@ -10,7 +10,7 @@ export class SimpleSchema extends Schema {
     #constraints;
     #gotValueFormatter;
     constructor(expected, guardFn, options = {}, refinements = {}) {
-        super();
+        super(options);
         this.#expected = expected;
         this.#guardFn = guardFn;
         this.#options = options;

package/schema/schemas/string.d.ts

@@ -1,6 +1,6 @@
 import { type SchemaPropertyDecorator, type SchemaPropertyDecoratorOptions } from '../decorators/index.js';
 import { SimpleSchema, type SimpleSchemaOptions } from './simple.js';
-export type StringSchemaOptions = SimpleSchemaOptions & {
+export type StringSchemaOptions = SimpleSchemaOptions<string> & {
     pattern?: RegExp | string;
     lowercase?: boolean;
 };

package/schema/schemas/string.js

@@ -1,5 +1,5 @@
 import { isDefined, isRegExp, isString } from '../../utils/type-guards.js';
-import { Property } from '../decorators/index.js';
+import { PropertySchema } from '../decorators/index.js';
 import { SimpleSchema } from './simple.js';
 export class StringSchema extends SimpleSchema {
     name = 'string';
@@ -27,5 +27,5 @@ export function string(options) {
     return new StringSchema(options);
 }
 export function StringProperty(options) {
-    return Property(string(options), options);
+    return PropertySchema((data) => string({ description: data.description, example: data.example, ...options }), options);
 }

package/schema/schemas/symbol.d.ts

@@ -1,9 +1,9 @@
-import type { JsonPath } from '../../json-path/json-path.js';
 import { type SchemaPropertyDecorator, type SchemaPropertyDecoratorOptions } from '../decorators/index.js';
-import { Schema, type SchemaTestOptions, type SchemaTestResult } from '../schema.js';
-export declare class SymbolSchema extends Schema<symbol> {
+import { SimpleSchema, type SimpleSchemaOptions } from './simple.js';
+export type SymbolSchemaOptions = SimpleSchemaOptions<symbol>;
+export declare class SymbolSchema extends SimpleSchema<symbol> {
     readonly name = "symbol";
-    _test(value: any, path: JsonPath, options: SchemaTestOptions): SchemaTestResult<symbol>;
+    constructor(options?: SymbolSchemaOptions);
 }
-export declare function symbol(): SymbolSchema;
-export declare function SymbolProperty(options?: SchemaPropertyDecoratorOptions): SchemaPropertyDecorator;
+export declare function symbol(options?: SymbolSchemaOptions): SymbolSchema;
+export declare function SymbolProperty(options?: SymbolSchemaOptions & SchemaPropertyDecoratorOptions): SchemaPropertyDecorator;

package/schema/schemas/symbol.js

@@ -1,20 +1,15 @@
-import { SchemaError } from '../../schema/schema.error.js';
 import { isSymbol } from '../../utils/type-guards.js';
-import { typeOf } from '../../utils/type-of.js';
-import { Property } from '../decorators/index.js';
-import { Schema } from '../schema.js';
-export class SymbolSchema extends Schema {
+import { PropertySchema } from '../decorators/index.js';
+import { SimpleSchema } from './simple.js';
+export class SymbolSchema extends SimpleSchema {
     name = 'symbol';
-    _test(value, path, options) {
-        if (isSymbol(value)) {
-            return { valid: true, value };
-        }
-        return { valid: false, error: SchemaError.expectedButGot('symbol', typeOf(value), path, { fast: options.fastErrors }) };
+    constructor(options) {
+        super('symbol', isSymbol, options);
     }
 }
-export function symbol() {
-    return new SymbolSchema();
+export function symbol(options) {
+    return new SymbolSchema(options);
 }
 export function SymbolProperty(options) {
-    return Property(symbol(), options);
+    return PropertySchema((data) => symbol({ description: data.description, example: data.example, ...options }), options);
 }

package/schema/schemas/uint8-array.d.ts

@@ -1,6 +1,6 @@
 import { type SchemaPropertyDecorator, type SchemaPropertyDecoratorOptions } from '../decorators/index.js';
 import { SimpleSchema, type SimpleSchemaOptions } from './simple.js';
-export type Uint8ArraySchemaOptions = SimpleSchemaOptions & {
+export type Uint8ArraySchemaOptions = SimpleSchemaOptions<Uint8Array> & {
     /** Minimum byte length */
     minimumLength?: number;
     /** Maximum byte length */

package/schema/schemas/uint8-array.js

@@ -1,5 +1,5 @@
 import { isDefined, isUint8Array } from '../../utils/type-guards.js';
-import { Property } from '../decorators/index.js';
+import { PropertySchema } from '../decorators/index.js';
 import { SimpleSchema } from './simple.js';
 export class Uint8ArraySchema extends SimpleSchema {
     name = 'Uint8Array';
@@ -20,5 +20,5 @@ export function uint8Array(options) {
     return new Uint8ArraySchema(options);
 }
 export function Uint8ArrayProperty(options) {
-    return Property(uint8Array(options), options);
+    return PropertySchema((data) => uint8Array({ description: data.description, example: data.example, ...options }), options);
 }

package/schema/schemas/union.js

@@ -1,5 +1,5 @@
 import { lazyProperty } from '../../utils/object/lazy-property.js';
-import { Property } from '../decorators/index.js';
+import { PropertySchema } from '../decorators/index.js';
 import { SchemaError } from '../schema.error.js';
 import { Schema } from '../schema.js';
 import { isSchemaTestable, schemaTestableToSchema } from '../testable.js';
@@ -35,8 +35,8 @@ export function union(...schemas) {
 export function Union(...schemasAndOptions) {
     const schemaOrOptions = schemasAndOptions.at(-1);
     if (isSchemaTestable(schemaOrOptions)) {
-        return Property(union(...schemasAndOptions));
+        return PropertySchema(() => union(...schemasAndOptions));
     }
     const schemas = schemasAndOptions.slice(0, -1);
-    return Property(union(...schemas), schemaOrOptions);
+    return PropertySchema(() => union(...schemas), schemaOrOptions);
 }

package/schema/schemas/unknown.d.ts

@@ -1,8 +1,9 @@
 import { type SchemaPropertyDecorator, type SchemaPropertyDecoratorOptions } from '../decorators/index.js';
-import { Schema, type SchemaTestResult } from '../schema.js';
+import { Schema, type SchemaOptions, type SchemaTestResult } from '../schema.js';
+export type UnknownSchemaOptions = SchemaOptions<unknown>;
 export declare class UnknownSchema extends Schema<unknown> {
     readonly name = "unknown";
     _test(value: unknown): SchemaTestResult<unknown>;
 }
-export declare function unknown(): UnknownSchema;
-export declare function Unknown(options?: SchemaPropertyDecoratorOptions): SchemaPropertyDecorator;
+export declare function unknown(options?: UnknownSchemaOptions): UnknownSchema;
+export declare function Unknown(options?: UnknownSchemaOptions & SchemaPropertyDecoratorOptions): SchemaPropertyDecorator;

package/schema/schemas/unknown.js

@@ -1,4 +1,4 @@
-import { Property } from '../decorators/index.js';
+import { PropertySchema } from '../decorators/index.js';
 import { Schema } from '../schema.js';
 export class UnknownSchema extends Schema {
     name = 'unknown';
@@ -6,9 +6,9 @@ export class UnknownSchema extends Schema {
         return { valid: true, value };
     }
 }
-export function unknown() {
-    return new UnknownSchema();
+export function unknown(options) {
+    return new UnknownSchema(options);
 }
 export function Unknown(options) {
-    return Property(unknown(), options);
+    return PropertySchema((data) => unknown({ description: data.description, example: data.example, ...options }), options);
 }

package/search-index/memory/memory-search-index.js

@@ -1,8 +1,8 @@
 import { compareByValueSelectionOrdered } from '../../utils/comparison.js';
 import { FactoryMap } from '../../utils/factory-map.js';
-import { normalizeText } from '../../utils/helpers.js';
 import { objectEntries } from '../../utils/object/object.js';
 import { intersectSets, unionSets } from '../../utils/set.js';
+import { normalizeText } from '../../utils/string/index.js';
 import { Timer } from '../../utils/timer.js';
 import { isDefined, isNullOrUndefined, isString } from '../../utils/type-guards.js';
 import { SearchIndex } from '../search-index.js';

package/types.d.ts

@@ -34,7 +34,7 @@ export type JsonPrimitive = string | number | boolean | null;
 export type JsonObject = {
     [key: string]: Json;
 };
-export type JsonArray = Json[];
+export type JsonArray = Json[] | readonly Json[];
 export type UndefinableJson = JsonPrimitive | UndefinableJsonObject | UndefinableJsonArray;
 export type UndefinableJsonInnerNode = UndefinableJsonPrimitive | UndefinableJsonObject | UndefinableJsonArray;
 export type UndefinableJsonPrimitive = JsonPrimitive | undefined;

package/utils/helpers.d.ts

@@ -25,44 +25,4 @@ export declare function parseFirstAndFamilyName(name: string): {
     firstName: string | undefined;
     familyName: string | undefined;
 };
-export type NormalizeTextOptions = {
-    /**
-     * Remove leading and trailing whitespace
-     */
-    trim?: boolean;
-    /**
-     * Lowercase all characters
-     */
-    lowercase?: boolean;
-    /**
-     * Remove multiple consecutive whitespace characters
-     */
-    multipleWhitespace?: boolean;
-    /**
-     * Remove diacritics (è -> e)
-     *
-     * applies unicode NFD normalization and removes diacritics
-     * @see unicode option
-     */
-    diacritics?: boolean;
-    /**
-     * Replace ligatures with their consecutive characters (æ -> ae)
-     *
-     * applies unicode NFKC normalization
-     * @see unicode option
-     */
-    ligatures?: boolean;
-    /**
-     * Unicode normalization
-     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize
-     */
-    unicode?: 'NFC' | 'NFD' | 'NFKC' | 'NFKD';
-};
-/**
- * Trims, lowercases, replaces multi-character whitespace with a single space and unicode normalization
- * @param text text to normalize
- * @param options specify what to normalize. Defaults to all except unicode
- * @returns normalized text
- */
-export declare function normalizeText(text: string, options?: NormalizeTextOptions): string;
 export declare function iif<T, F>(condition: boolean, trueFn: () => T, falseFn: () => F): T | F;

package/utils/helpers.js

@@ -1,7 +1,6 @@
 import { supportsNotification } from '../supports.js';
 import { DetailsError } from '../errors/details.error.js';
 import { decycle } from './object/decycle.js';
-import { isDefined } from './type-guards.js';
 /**
  * Create an structured clone of an value using Notification if available, otherwise history state (may alters history)
  *
@@ -68,34 +67,6 @@ export function parseFirstAndFamilyName(name) {
         familyName: familyName.length > 0 ? familyName : undefined
     };
 }
-/**
- * Trims, lowercases, replaces multi-character whitespace with a single space and unicode normalization
- * @param text text to normalize
- * @param options specify what to normalize. Defaults to all except unicode
- * @returns normalized text
- */
-export function normalizeText(text, options = { trim: true, lowercase: true, multipleWhitespace: true, diacritics: true, ligatures: true }) {
-    let normalized = text;
-    if (options.trim == true) {
-        normalized = normalized.trim();
-    }
-    if (options.lowercase == true) {
-        normalized = normalized.toLowerCase();
-    }
-    if (options.multipleWhitespace == true) {
-        normalized = normalized.replace(/\s+/ug, ' ');
-    }
-    if (options.diacritics == true) {
-        normalized = normalized.normalize('NFD').replace(/\p{Diacritic}/ug, '');
-    }
-    if (options.ligatures == true) {
-        normalized = normalized.normalize('NFKC');
-    }
-    if (isDefined(options.unicode)) {
-        normalized = normalized.normalize(options.unicode);
-    }
-    return normalized;
-}
 export function iif(condition, trueFn, falseFn) {
     return condition ? trueFn() : falseFn();
 }

package/utils/index.d.ts

@@ -49,6 +49,7 @@ export * from './sort.js';
 export * from './throw.js';
 export * from './timer.js';
 export * from './timing.js';
+export * from './try-ignore.js';
 export * from './type-guards.js';
 export * from './type-of.js';
 export * from './type/index.js';

package/utils/index.js

@@ -49,6 +49,7 @@ export * from './sort.js';
 export * from './throw.js';
 export * from './timer.js';
 export * from './timing.js';
+export * from './try-ignore.js';
 export * from './type-guards.js';
 export * from './type-of.js';
 export * from './type/index.js';

package/utils/string/index.d.ts

@@ -1,4 +1,5 @@
 export * from './hypenate.js';
+export * from './normalize.js';
 export * from './snake-case.js';
 export * from './title-case.js';
 export * from './trim.js';

package/utils/string/index.js

@@ -1,4 +1,5 @@
 export * from './hypenate.js';
+export * from './normalize.js';
 export * from './snake-case.js';
 export * from './title-case.js';
 export * from './trim.js';

package/utils/string/normalize.d.ts

@@ -0,0 +1,50 @@
+export type NormalizeTextOptions = {
+    /**
+     * Remove leading and trailing whitespace
+     */
+    trim?: boolean;
+    /**
+     * Lowercase all characters
+     */
+    lowercase?: boolean;
+    /**
+     * Remove multiple consecutive whitespace characters
+     */
+    multipleWhitespace?: boolean;
+    /**
+     * Remove diacritics (è -> e)
+     *
+     * applies unicode NFD normalization and removes diacritics
+     * @see unicode option
+     */
+    diacritics?: boolean;
+    /**
+     * Replace ligatures with their consecutive characters (æ -> ae)
+     *
+     * applies unicode NFKC normalization
+     * @see unicode option
+     */
+    ligatures?: boolean;
+    /**
+     * Unicode normalization
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize
+     */
+    unicode?: 'NFC' | 'NFD' | 'NFKC' | 'NFKD';
+};
+/**
+ * Trims, lowercases, replaces multi-character whitespace with a single space and unicode normalization
+ * @param text text to normalize
+ * @param options specify what to normalize. Defaults to all except unicode
+ * @returns normalized text
+ */
+export declare function normalizeText(text: string, options?: NormalizeTextOptions): string;
+/**
+ * Normalizes text input by trimming whitespace and returning null if text is empty.
+ *
+ * @param text The input text to normalize
+ * @param allowNull If true, null or undefined input (or input that becomes empty after trimming) will return null. If false, an error will be thrown in these cases. Defaults to true.
+ * @returns The trimmed string. If allowNull is true and the input is null, undefined, or empty after trimming, returns null.
+ * @throws {Error} If allowNull is false and the input is null, undefined, or empty after trimming.
+ */
+export declare function normalizeTextInput(text: string | null | undefined, allowNull?: true): string | null;
+export declare function normalizeTextInput(text: string | null | undefined, allowNull: false): string;

package/utils/string/normalize.js

@@ -0,0 +1,39 @@
+import { isDefined, isNullOrUndefined } from '../type-guards.js';
+/**
+ * Trims, lowercases, replaces multi-character whitespace with a single space and unicode normalization
+ * @param text text to normalize
+ * @param options specify what to normalize. Defaults to all except unicode
+ * @returns normalized text
+ */
+export function normalizeText(text, options = { trim: true, lowercase: true, multipleWhitespace: true, diacritics: true, ligatures: true }) {
+    let normalized = text;
+    if (options.trim == true) {
+        normalized = normalized.trim();
+    }
+    if (options.lowercase == true) {
+        normalized = normalized.toLowerCase();
+    }
+    if (options.multipleWhitespace == true) {
+        normalized = normalized.replace(/\s+/ug, ' ');
+    }
+    if (options.diacritics == true) {
+        normalized = normalized.normalize('NFD').replace(/\p{Diacritic}/ug, '');
+    }
+    if (options.ligatures == true) {
+        normalized = normalized.normalize('NFKC');
+    }
+    if (isDefined(options.unicode)) {
+        normalized = normalized.normalize(options.unicode);
+    }
+    return normalized;
+}
+export function normalizeTextInput(text, allowNull) {
+    const normalized = text?.trim();
+    if (isNullOrUndefined(normalized) || (normalized.length == 0)) {
+        if (allowNull == false) {
+            throw new Error('Invalid input.');
+        }
+        return null;
+    }
+    return normalized;
+}

package/utils/try-ignore.d.ts

@@ -0,0 +1,2 @@
+export declare function tryIgnore(fn: () => any): void;
+export declare function tryIgnoreAsync(fn: () => Promise<any>): Promise<void>;

package/utils/try-ignore.js

@@ -0,0 +1,12 @@
+export function tryIgnore(fn) {
+    try {
+        fn();
+    }
+    catch { /* ignore */ }
+}
+export async function tryIgnoreAsync(fn) {
+    try {
+        await fn();
+    }
+    catch { /* ignore */ }
+}