@infra-blocks/types 0.26.0 → 0.27.0-alpha.1

package/lib/cjs/index.d.ts

@@ -5,6 +5,8 @@ export * from "./types.js";
 /**
  * A function for forcing exhaustiveness in switch statements or if-else chains.
  *
+ * Throws an assertion error at runtime if called. The message can be specified as the second argument.
+ *
  * @example
  * type BigType = "penus" | "penii";
  * function doStuff(x: BigType) {
@@ -23,7 +25,7 @@ export * from "./types.js";
  *
  * @param value - The value to validate against never.
  */
-export declare function unreachable(value: never): never;
+export declare function unreachable(_: never, message?: string): never;
 /**
  * A function to mark a value as trusted for a type cast that can leverage inference.
  *

package/lib/cjs/index.js

@@ -16,13 +16,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.unreachable = unreachable;
 exports.trusted = trusted;
+const node_assert_1 = require("node:assert");
 __exportStar(require("./func.js"), exports);
 __exportStar(require("./guard.js"), exports);
 __exportStar(require("./predicates.js"), exports);
 __exportStar(require("./types.js"), exports);
+// TODO: Message type, that is either: undefined, a string, a string followed by format args or a function returning a string.
 /**
  * A function for forcing exhaustiveness in switch statements or if-else chains.
  *
+ * Throws an assertion error at runtime if called. The message can be specified as the second argument.
+ *
  * @example
  * type BigType = "penus" | "penii";
  * function doStuff(x: BigType) {
@@ -41,8 +45,8 @@ __exportStar(require("./types.js"), exports);
  *
  * @param value - The value to validate against never.
  */
-function unreachable(value) {
-    return value;
+function unreachable(_, message) {
+    (0, node_assert_1.fail)(message ?? "unreachable code reached!");
 }
 /**
  * A function to mark a value as trusted for a type cast that can leverage inference.

package/lib/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AA0BA,kCAEC;AAsBD,0BAEC;AApDD,4CAA0B;AAC1B,6CAA2B;AAC3B,kDAAgC;AAChC,6CAA2B;AAE3B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,WAAW,CAAC,KAAY;IACtC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,OAAO,CAAI,KAAc;IACvC,OAAO,KAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AA+BA,kCAEC;AAsBD,0BAEC;AAzDD,6CAAmC;AAEnC,4CAA0B;AAC1B,6CAA2B;AAC3B,kDAAgC;AAChC,6CAA2B;AAE3B,8HAA8H;AAC9H;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,WAAW,CAAC,CAAQ,EAAE,OAAgB;IACpD,IAAA,kBAAI,EAAC,OAAO,IAAI,2BAA2B,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,OAAO,CAAI,KAAc;IACvC,OAAO,KAAU,CAAC;AACpB,CAAC"}

package/lib/cjs/types.d.ts

@@ -58,6 +58,12 @@ export type Nullable<T> = T | null | undefined;
  * This is in contrast to the built-in `Partial` type which makes all fields optional.
  */
 export type Optional<T, K extends keyof T = keyof T> = Partial<Pick<T, K>> & Omit<T, K>;
+/**
+ * A utility type for tracking a phantom type parameter.
+ */
+export type Phantom<T> = {
+    _phantom?: T;
+};
 /**
  * A union type that includes all primitive types.
  */

package/lib/esm/index.d.ts

@@ -5,6 +5,8 @@ export * from "./types.js";
 /**
  * A function for forcing exhaustiveness in switch statements or if-else chains.
  *
+ * Throws an assertion error at runtime if called. The message can be specified as the second argument.
+ *
  * @example
  * type BigType = "penus" | "penii";
  * function doStuff(x: BigType) {
@@ -23,7 +25,7 @@ export * from "./types.js";
  *
  * @param value - The value to validate against never.
  */
-export declare function unreachable(value: never): never;
+export declare function unreachable(_: never, message?: string): never;
 /**
  * A function to mark a value as trusted for a type cast that can leverage inference.
  *

package/lib/esm/index.js

@@ -1,10 +1,14 @@
+import { fail } from "node:assert";
 export * from "./func.js";
 export * from "./guard.js";
 export * from "./predicates.js";
 export * from "./types.js";
+// TODO: Message type, that is either: undefined, a string, a string followed by format args or a function returning a string.
 /**
  * A function for forcing exhaustiveness in switch statements or if-else chains.
  *
+ * Throws an assertion error at runtime if called. The message can be specified as the second argument.
+ *
  * @example
  * type BigType = "penus" | "penii";
  * function doStuff(x: BigType) {
@@ -23,8 +27,8 @@ export * from "./types.js";
  *
  * @param value - The value to validate against never.
  */
-export function unreachable(value) {
-    return value;
+export function unreachable(_, message) {
+    fail(message ?? "unreachable code reached!");
 }
 /**
  * A function to mark a value as trusted for a type cast that can leverage inference.

package/lib/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,OAAO,CAAI,KAAc;IACvC,OAAO,KAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAE3B,8HAA8H;AAC9H;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,WAAW,CAAC,CAAQ,EAAE,OAAgB;IACpD,IAAI,CAAC,OAAO,IAAI,2BAA2B,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,OAAO,CAAI,KAAc;IACvC,OAAO,KAAU,CAAC;AACpB,CAAC"}

package/lib/esm/types.d.ts

@@ -58,6 +58,12 @@ export type Nullable<T> = T | null | undefined;
  * This is in contrast to the built-in `Partial` type which makes all fields optional.
  */
 export type Optional<T, K extends keyof T = keyof T> = Partial<Pick<T, K>> & Omit<T, K>;
+/**
+ * A utility type for tracking a phantom type parameter.
+ */
+export type Phantom<T> = {
+    _phantom?: T;
+};
 /**
  * A union type that includes all primitive types.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infra-blocks/types",
-  "version": "0.26.0",
+  "version": "0.27.0-alpha.1",
   "description": "Typescript types utility package.",
   "keywords": [
     "type",