@infra-blocks/types 0.20.0 → 0.21.0

package/lib/cjs/func.d.ts

@@ -9,16 +9,28 @@ export type AbstractConstructor<R = object, A extends any[] = any[]> = abstract
  */
 export type AsyncFactory<P extends unknown[], R> = (...params: P) => Promise<R>;
 /**
- * A type alias for asynchronous provider functions.
+ * The async flavor of {@link Parser}.
+ */
+export type AsyncParser<Output, Input = unknown> = (input: Input) => Promise<Output>;
+/**
+ * The async flavor of {@link Predicate}.
+ */
+export type AsyncPredicate<T> = (item: T) => Promise<boolean>;
+/**
+ * The async flavor of {@link Provider}.
  */
 export type AsyncProvider<T> = () => Promise<T>;
 /**
- * Convenient type to easily represent "callable" types and to avoid using
+ * The async flavor of {@link Transform}.
+ */
+export type AsyncTransform<I, O> = (input: I) => Promise<O>;
+/**
+ * Convenient type to easily represent any "callable" types and to avoid using
  * "any" in client code.
  */
 export type Callable = (...args: never[]) => unknown;
 /**
- * Convenient type alias for constructors.
+ * Convenient type alias for *callable* constructors (excluding abstract ones).
  */
 export type Constructor<R = object, A extends any[] = any[]> = new (...args: A) => R;
 /**
@@ -29,6 +41,15 @@ export type ErrorHandler<T extends Error = Error> = (err: T) => void;
  * A type alias for a function that creates objects of a given type.
  */
 export type Factory<P extends unknown[], R> = (...params: P) => R;
+/**
+ * A type alias for parser functions.
+ *
+ * The input of parser functions defaults to `unknown`, but can be specified.
+ * Parsers are functions that take loosely typed input and return a stricter version,
+ * often performing validation in the process. Parsers should be expected to throw
+ * errors on validation failures.
+ */
+export type Parser<O, I = unknown> = Transform<I, O>;
 /**
  * A type alias for single element predicate functions.
  */
@@ -37,6 +58,14 @@ export type Predicate<T> = (item: T) => boolean;
  * A type alias for functions that return a value of a given type without arguments.
  */
 export type Provider<T> = () => T;
+/**
+ * A type alias for transformation functions.
+ *
+ * A transform takes a value of type I and returns a value of type O. Unlike {@link Parser},
+ * transforms are typically not expected to perform validation and therefore aren't
+ * expected to throw errors.
+ */
+export type Transform<I, O> = (input: I) => O;
 /**
  * A type alias for type guards.
  */

package/lib/esm/func.d.ts

@@ -9,16 +9,28 @@ export type AbstractConstructor<R = object, A extends any[] = any[]> = abstract
  */
 export type AsyncFactory<P extends unknown[], R> = (...params: P) => Promise<R>;
 /**
- * A type alias for asynchronous provider functions.
+ * The async flavor of {@link Parser}.
+ */
+export type AsyncParser<Output, Input = unknown> = (input: Input) => Promise<Output>;
+/**
+ * The async flavor of {@link Predicate}.
+ */
+export type AsyncPredicate<T> = (item: T) => Promise<boolean>;
+/**
+ * The async flavor of {@link Provider}.
  */
 export type AsyncProvider<T> = () => Promise<T>;
 /**
- * Convenient type to easily represent "callable" types and to avoid using
+ * The async flavor of {@link Transform}.
+ */
+export type AsyncTransform<I, O> = (input: I) => Promise<O>;
+/**
+ * Convenient type to easily represent any "callable" types and to avoid using
  * "any" in client code.
  */
 export type Callable = (...args: never[]) => unknown;
 /**
- * Convenient type alias for constructors.
+ * Convenient type alias for *callable* constructors (excluding abstract ones).
  */
 export type Constructor<R = object, A extends any[] = any[]> = new (...args: A) => R;
 /**
@@ -29,6 +41,15 @@ export type ErrorHandler<T extends Error = Error> = (err: T) => void;
  * A type alias for a function that creates objects of a given type.
  */
 export type Factory<P extends unknown[], R> = (...params: P) => R;
+/**
+ * A type alias for parser functions.
+ *
+ * The input of parser functions defaults to `unknown`, but can be specified.
+ * Parsers are functions that take loosely typed input and return a stricter version,
+ * often performing validation in the process. Parsers should be expected to throw
+ * errors on validation failures.
+ */
+export type Parser<O, I = unknown> = Transform<I, O>;
 /**
  * A type alias for single element predicate functions.
  */
@@ -37,6 +58,14 @@ export type Predicate<T> = (item: T) => boolean;
  * A type alias for functions that return a value of a given type without arguments.
  */
 export type Provider<T> = () => T;
+/**
+ * A type alias for transformation functions.
+ *
+ * A transform takes a value of type I and returns a value of type O. Unlike {@link Parser},
+ * transforms are typically not expected to perform validation and therefore aren't
+ * expected to throw errors.
+ */
+export type Transform<I, O> = (input: I) => O;
 /**
  * A type alias for type guards.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infra-blocks/types",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Typescript types utility package.",
   "keywords": [
     "type",
@@ -46,6 +46,7 @@
     "@typescript-eslint/parser": "^5.59.8",
     "c8": "^8.0.0",
     "conditional-type-checks": "^1.0.6",
+    "expect-type": "^1.3.0",
     "lefthook": "^2.0.8",
     "mocha": "^10.2.0",
     "ts-node": "^10.9.1",