feat(hf): asserts

mathcovax · mathcovax · commit 1c4402b5f1e1 · 2026-01-16T12:07:47.000Z
diff --git a/docs/en/v1/api/common/asserts.md b/docs/en/v1/api/common/asserts.md
@@ -0,0 +1,48 @@
+---
+outline: [2, 3]
+description: "The asserts() function throws when a predicate fails and narrows the input type when it passes."
+prev:
+  text: "isType"
+  link: "/en/v1/api/common/isType"
+next:
+  text: "instanceOf"
+  link: "/en/v1/api/common/instanceOf"
+---
+
+# asserts
+
+The **`asserts()`** function throws when a predicate fails and narrows the input type when it passes.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/common/asserts/tryout.doc.ts"
+  majorVersion="v1"
+  height="460px"
+/>
+
+## Syntax
+
+```typescript
+function asserts<
+	GenericInput extends unknown,
+	GenericPredicate extends GenericInput
+>(
+	input: GenericInput,
+	predicate: (input: GenericInput) => input is GenericPredicate
+): asserts input is GenericPredicate
+```
+
+## Parameters
+
+- `input`: The value to validate.
+- `predicate`: A type-guard predicate used to validate and narrow the input.
+
+## Return value
+
+Nothing. It throws an `AssertsError` when the predicate fails.
+
+## See also
+
+- [`isType`](/en/v1/api/common/isType) - Builds type guards based on runtime checks
+- [`instanceOf`](/en/v1/api/common/instanceOf) - Type guard using constructors
diff --git a/docs/en/v1/api/common/index.md b/docs/en/v1/api/common/index.md
@@ -73,6 +73,9 @@ Compares to one or multiple literal values with support for type guards on primi
 ### [isType](/en/v1/api/common/isType)
 Type guard based on `typeof`, `Array.isArray`, iterables, etc.
 
+### [asserts](/en/v1/api/common/asserts)
+Throws when a predicate fails and narrows the input type when it passes.
+
 ### [instanceOf](/en/v1/api/common/instanceOf)
 Type guard based on one or more constructors (typed `instanceof`).
 
diff --git a/docs/en/v1/api/common/instanceOf.md b/docs/en/v1/api/common/instanceOf.md
@@ -2,8 +2,8 @@
 outline: [2, 3]
 description: "The instanceOf() function creates a type guard based on one or several constructors. It checks instanceof while keeping precise typing."
 prev:
-  text: "isType"
-  link: "/en/v1/api/common/isType"
+  text: "asserts"
+  link: "/en/v1/api/common/asserts"
 next:
   text: "hasKinds"
   link: "/en/v1/api/common/hasKinds"
diff --git a/docs/en/v1/api/common/isType.md b/docs/en/v1/api/common/isType.md
@@ -5,8 +5,8 @@ prev:
   text: "equal"
   link: "/en/v1/api/common/equal"
 next:
-  text: "instanceOf"
-  link: "/en/v1/api/common/instanceOf"
+  text: "asserts"
+  link: "/en/v1/api/common/asserts"
 ---
 
 # isType
diff --git a/docs/examples/v1/api/common/asserts/tryout.doc.ts b/docs/examples/v1/api/common/asserts/tryout.doc.ts
@@ -0,0 +1,20 @@
+import { asserts, type ExpectType, isType } from "@duplojs/utils";
+
+const value = "demo" as string | number;
+asserts(value, isType("string"));
+
+type checkString = ExpectType<
+	typeof value,
+	string,
+	"strict"
+>;
+
+const maybeId = 42 as number | undefined;
+asserts(maybeId, isType("number"));
+
+type checkNumber = ExpectType<
+	typeof maybeId,
+	number,
+	"strict"
+>;
+
diff --git a/docs/fr/v1/api/common/asserts.md b/docs/fr/v1/api/common/asserts.md
@@ -0,0 +1,48 @@
+---
+outline: [2, 3]
+description: "La fonction asserts() lance une erreur si le predicate echoue et affine le type si il passe."
+prev:
+  text: "isType"
+  link: "/fr/v1/api/common/isType"
+next:
+  text: "instanceOf"
+  link: "/fr/v1/api/common/instanceOf"
+---
+
+# asserts
+
+La **`asserts()`** fonction lance une erreur si le predicate echoue et affine le type si il passe.
+
+## Exemple interactif
+
+<MonacoTSEditor
+  src="/examples/v1/api/common/asserts/tryout.doc.ts"
+  majorVersion="v1"
+  height="460px"
+/>
+
+## Syntaxe
+
+```typescript
+function asserts<
+	GenericInput extends unknown,
+	GenericPredicate extends GenericInput
+>(
+	input: GenericInput,
+	predicate: (input: GenericInput) => input is GenericPredicate
+): asserts input is GenericPredicate
+```
+
+## Parametres
+
+- `input` : La valeur a valider.
+- `predicate` : Un predicate type guard pour valider et affiner l'entree.
+
+## Valeur de retour
+
+Rien. Elle lance un `AssertsError` quand le predicate echoue.
+
+## Voir aussi
+
+- [`isType`](/fr/v1/api/common/isType) - Cree un type guard base sur des verifications runtime
+- [`instanceOf`](/fr/v1/api/common/instanceOf) - Type guard via des constructeurs
diff --git a/docs/fr/v1/api/common/index.md b/docs/fr/v1/api/common/index.md
@@ -73,6 +73,9 @@ Compare à une ou plusieurs valeurs littérales avec support des type guards sur
 ### [isType](/fr/v1/api/common/isType)
 Type guard basé sur `typeof`, `Array.isArray`, itérables, etc.
 
+### [asserts](/fr/v1/api/common/asserts)
+Lance une erreur si le predicate echoue et affine le type si il passe.
+
 ### [instanceOf](/fr/v1/api/common/instanceOf)
 Type guard basé sur un ou plusieurs constructeurs (`instanceof` typé).
 
diff --git a/docs/fr/v1/api/common/instanceOf.md b/docs/fr/v1/api/common/instanceOf.md
@@ -2,8 +2,8 @@
 outline: [2, 3]
 description: "La fonction instanceOf() crée un type guard basé sur un ou plusieurs constructeurs. Elle vérifie instanceof en conservant un typage précis."
 prev:
-  text: "isType"
-  link: "/fr/v1/api/common/isType"
+  text: "asserts"
+  link: "/fr/v1/api/common/asserts"
 next:
   text: "hasKinds"
   link: "/fr/v1/api/common/hasKinds"
diff --git a/docs/fr/v1/api/common/isType.md b/docs/fr/v1/api/common/isType.md
@@ -5,8 +5,8 @@ prev:
   text: "equal"
   link: "/fr/v1/api/common/equal"
 next:
-  text: "instanceOf"
-  link: "/fr/v1/api/common/instanceOf"
+  text: "asserts"
+  link: "/fr/v1/api/common/asserts"
 ---
 
 # isType
diff --git a/docs/public/libs/v1/common/asserts.cjs b/docs/public/libs/v1/common/asserts.cjs
@@ -0,0 +1,23 @@
+'use strict';
+
+var errorKindNamespace = require('./errorKindNamespace.cjs');
+var kind = require('./kind.cjs');
+
+class AssertsError extends kind.kindHeritage("asserts-error", errorKindNamespace.createErrorKind("asserts-error"), Error) {
+    value;
+    constructor(value) {
+        super({}, ["Asserts Error."]);
+        this.value = value;
+    }
+}
+/**
+ * {@include common/asserts/index.md}
+ */
+function asserts(input, predicate) {
+    if (!predicate(input)) {
+        throw new AssertsError(input);
+    }
+}
+
+exports.AssertsError = AssertsError;
+exports.asserts = asserts;
diff --git a/docs/public/libs/v1/common/asserts.d.ts b/docs/public/libs/v1/common/asserts.d.ts
@@ -0,0 +1,38 @@
+declare const AssertsError_base: new (params: {
+    "@DuplojsUtilsError/asserts-error"?: unknown;
+}, parentParams: [message?: string | undefined, options?: ErrorOptions | undefined]) => Error & import("./kind").Kind<import("./kind").KindDefinition<"asserts-error", unknown>, unknown> & import("./kind").Kind<import("./kind").KindDefinition<"@DuplojsUtilsError/asserts-error", unknown>, unknown>;
+export declare class AssertsError extends AssertsError_base {
+    value: unknown;
+    constructor(value: unknown);
+}
+/**
+ * The asserts() function throws when a predicate fails and narrows the input type when it passes.
+ * 
+ * **Supported call styles:**
+ * - Classic: `asserts(input, predicate)` → narrows the input type or throws
+ * 
+ * It throws an `AssertsError` with the failing input value.
+ * 
+ * ```ts
+ * const input: string | number = "demo";
+ * asserts(input, isType("string"));
+ * 
+ * const payload: { id?: number } = { id: 1 };
+ * asserts(payload.id, isType("undefined"));
+ * 
+ * try {
+ * 	asserts(42 as string | number, isType("string"));
+ * } catch (error) {
+ * 	if (error instanceof AssertsError) {
+ * 		const failedValue = error.value;
+ * 	}
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/asserts
+ * 
+ * @namespace C
+ * 
+ */
+export declare function asserts<GenericInput extends unknown, GenericPredicate extends GenericInput>(input: GenericInput, predicate: (input: GenericInput) => input is GenericPredicate): asserts input is GenericPredicate;
+export {};
diff --git a/docs/public/libs/v1/common/asserts.mjs b/docs/public/libs/v1/common/asserts.mjs
@@ -0,0 +1,20 @@
+import { createErrorKind } from './errorKindNamespace.mjs';
+import { kindHeritage } from './kind.mjs';
+
+class AssertsError extends kindHeritage("asserts-error", createErrorKind("asserts-error"), Error) {
+    value;
+    constructor(value) {
+        super({}, ["Asserts Error."]);
+        this.value = value;
+    }
+}
+/**
+ * {@include common/asserts/index.md}
+ */
+function asserts(input, predicate) {
+    if (!predicate(input)) {
+        throw new AssertsError(input);
+    }
+}
+
+export { AssertsError, asserts };
diff --git a/docs/public/libs/v1/common/index.d.ts b/docs/public/libs/v1/common/index.d.ts
@@ -14,7 +14,7 @@
  * 
  * What you will find in this namespace:
  * - composition helpers (`pipe`, `innerPipe`, `asyncPipe`, `asyncInnerPipe`, `forward`)
- * - predicates and guards (`when`, `whenNot`, `whenElse`, `and`, `or`, `isType`, `instanceOf`)
+ * - predicates and guards (`when`, `whenNot`, `whenElse`, `and`, `or`, `isType`, `asserts`, `instanceOf`)
  * - control flow (`loop`, `asyncLoop`, `asyncRetry`, `sleep`, `memo`)
  * - promise utilities (`externalPromise`, `promiseObject`)
  * - string and value conversions (`toString`, `stringToMillisecond`, `stringToBytes`, `escapeRegExp`)
@@ -74,3 +74,4 @@ export * from "./hasSomeKinds";
 export * from "./hasKinds";
 export * from "./toCurriedPredicate";
 export * from "./pipeCall";
+export * from "./asserts";
diff --git a/docs/public/libs/v1/common/types/index.d.ts b/docs/public/libs/v1/common/types/index.d.ts
@@ -44,3 +44,4 @@ export * from "./sortType";
 export * from "./maybeGetter";
 export * from "./falsyValue";
 export * from "./DeepReadonly";
+export * from "./json";
diff --git a/docs/public/libs/v1/common/types/json.d.ts b/docs/public/libs/v1/common/types/json.d.ts
@@ -0,0 +1,4 @@
+import { type MaybeArray } from "./maybeArray";
+export type Json = MaybeArray<string | undefined | boolean | number | null | {
+    [key: string]: Json;
+}>;
diff --git a/docs/public/libs/v1/index.cjs b/docs/public/libs/v1/index.cjs
@@ -60,6 +60,7 @@ var hasSomeKinds = require('./common/hasSomeKinds.cjs');
 var hasKinds = require('./common/hasKinds.cjs');
 var toCurriedPredicate = require('./common/toCurriedPredicate.cjs');
 var pipeCall = require('./common/pipeCall.cjs');
+var asserts = require('./common/asserts.cjs');
 
 
 
@@ -147,3 +148,5 @@ exports.hasSomeKinds = hasSomeKinds.hasSomeKinds;
 exports.hasKinds = hasKinds.hasKinds;
 exports.toCurriedPredicate = toCurriedPredicate.toCurriedPredicate;
 exports.pipeCall = pipeCall.pipeCall;
+exports.AssertsError = asserts.AssertsError;
+exports.asserts = asserts.asserts;
diff --git a/docs/public/libs/v1/index.mjs b/docs/public/libs/v1/index.mjs
@@ -82,3 +82,4 @@ export { hasSomeKinds } from './common/hasSomeKinds.mjs';
 export { hasKinds } from './common/hasKinds.mjs';
 export { toCurriedPredicate } from './common/toCurriedPredicate.mjs';
 export { pipeCall } from './common/pipeCall.mjs';
+export { AssertsError, asserts } from './common/asserts.mjs';
diff --git a/docs/public/libs/v1/metadata.json b/docs/public/libs/v1/metadata.json
@@ -1074,6 +1074,9 @@
             {
               "name": "isUnion.d.ts"
             },
+            {
+              "name": "json.d.ts"
+            },
             {
               "name": "lastUnionElement.d.ts"
             },
@@ -1166,6 +1169,15 @@
         {
           "name": "and.mjs"
         },
+        {
+          "name": "asserts.cjs"
+        },
+        {
+          "name": "asserts.d.ts"
+        },
+        {
+          "name": "asserts.mjs"
+        },
         {
           "name": "asyncInnerPipe.cjs"
         },
diff --git a/jsDoc/common/asserts/example.ts b/jsDoc/common/asserts/example.ts
@@ -0,0 +1,15 @@
+import { asserts, isType, AssertsError } from "@scripts";
+
+const input: string | number = "demo";
+asserts(input, isType("string"));
+
+const payload: { id?: number } = { id: 1 };
+asserts(payload.id, isType("undefined"));
+
+try {
+	asserts(42 as string | number, isType("string"));
+} catch (error) {
+	if (error instanceof AssertsError) {
+		const failedValue = error.value;
+	}
+}
diff --git a/jsDoc/common/asserts/index.md b/jsDoc/common/asserts/index.md
@@ -0,0 +1,14 @@
+The asserts() function throws when a predicate fails and narrows the input type when it passes.
+
+**Supported call styles:**
+- Classic: `asserts(input, predicate)` → narrows the input type or throws
+
+It throws an `AssertsError` with the failing input value.
+
+```ts
+{@include common/asserts/example.ts[3,15]}
+```
+
+@see https://utils.duplojs.dev/en/v1/api/common/asserts
+
+@namespace C
diff --git a/jsDoc/common/index.md b/jsDoc/common/index.md
@@ -13,7 +13,7 @@ import { pipe, when, clone } from "@duplojs/utils/common";
 
 What you will find in this namespace:
 - composition helpers (`pipe`, `innerPipe`, `asyncPipe`, `asyncInnerPipe`, `forward`)
-- predicates and guards (`when`, `whenNot`, `whenElse`, `and`, `or`, `isType`, `instanceOf`)
+- predicates and guards (`when`, `whenNot`, `whenElse`, `and`, `or`, `isType`, `asserts`, `instanceOf`)
 - control flow (`loop`, `asyncLoop`, `asyncRetry`, `sleep`, `memo`)
 - promise utilities (`externalPromise`, `promiseObject`)
 - string and value conversions (`toString`, `stringToMillisecond`, `stringToBytes`, `escapeRegExp`)
diff --git a/scripts/common/asserts.ts b/scripts/common/asserts.ts
diff --git a/scripts/common/index.ts b/scripts/common/index.ts
diff --git a/tests/common/asserts.test.ts b/tests/common/asserts.test.ts
