@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.10

package/docs/API/10-lang/10-array/10-fill.ts

@@ -0,0 +1,34 @@
+/**
+ * @title DArray.fill
+ *
+ * Remplacer une plage d’éléments par une valeur dans une nouvelle copie du tableau.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const numbers = [1, 2, 3, 4];
+
+// Appel classique : les indices 1 et 2 sont remplacés.
+const result = DArray.fill(numbers, 0, 1, 3);
+
+// La valeur obtenue est [1, 0, 0, 4] ; numbers reste inchangé.
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[], "strict">;
+
+// Appel curifié : la valeur et la plage sont fixées dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.fill(9, 0, 2),
+);
+
+// La valeur obtenue est [9, 9, 3, 4].
+type _CheckPiped = DCommon.ExpectType<typeof piped, readonly number[], "strict">;
+
+// La borne maximale du tableau source est conservée après le remplacement.
+declare const constrained: readonly number[] & DArray.MaxElements<4>;
+const constrainedResult = DArray.fill(constrained, 0, 0, 1);
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	readonly number[] & DArray.MaxElements<4>,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-fillAll.ts

@@ -0,0 +1,34 @@
+/**
+ * @title DArray.fillAll
+ *
+ * Remplacer tous les éléments d’un tableau par une même valeur dans une nouvelle copie.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const values = [1, 2, 3];
+
+// Appel classique : tous les éléments deviennent 0.
+const result = DArray.fillAll(values, 0);
+
+// La valeur obtenue est [0, 0, 0] ; values reste inchangé.
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[], "strict">;
+
+// Appel curifié : la valeur de remplacement est configurée dans l’étape du pipe.
+const piped = DCommon.pipe(
+	values,
+	DArray.fillAll(9),
+);
+
+// La valeur obtenue est [9, 9, 9].
+type _CheckPiped = DCommon.ExpectType<typeof piped, readonly number[], "strict">;
+
+// Le remplissage conserve la borne maximale portée par le tableau source.
+declare const constrained: readonly number[] & DArray.MaxElements<4>;
+const constrainedResult = DArray.fillAll(constrained, 0);
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	readonly number[] & DArray.MaxElements<4>,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-filter.ts

@@ -0,0 +1,43 @@
+/**
+ * @title DArray.filter
+ *
+ * Construire un nouveau tableau avec les éléments qui satisfont un prédicat.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+const numbers = [1, 2, 3, 4];
+
+// Appel classique : seuls les nombres pairs sont conservés.
+const result = DArray.filter(numbers, DNumber.isEven);
+
+// La valeur obtenue est [2, 4].
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	readonly (number & DNumber.Even)[],
+	"strict"
+>;
+
+// Appel curifié : le prédicat est utilisé dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.filter(DNumber.greaterThan(2)),
+);
+
+// La valeur obtenue est [3, 4].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	readonly (number & DNumber.GreaterThan<2>)[],
+	"strict"
+>;
+
+// Le filtrage ne peut pas augmenter le nombre d’éléments : la borne maximale est conservée.
+declare const constrained: readonly number[] & DArray.MaxElements<4>;
+const constrainedResult = DArray.filter(constrained, DNumber.greaterThan(1));
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	readonly (number & DNumber.GreaterThan<1>)[] & DArray.MaxElements<4>,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-find.ts

@@ -0,0 +1,33 @@
+/**
+ * @title DArray.find
+ *
+ * Lire le premier élément satisfaisant un prédicat, ou undefined si aucun ne convient.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+const numbers = [1, 2, 3];
+
+// Appel classique : le premier élément supérieur à 1 est retourné.
+const result = DArray.find(numbers, DNumber.greaterThan(1));
+
+// La valeur obtenue est 2 ; l’absence d’élément reste représentée par undefined dans le type.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	(number & DNumber.GreaterThan<1>) | undefined,
+	"strict"
+>;
+
+// Appel curifié : le prédicat est configuré dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.find(DNumber.greaterThan(2)),
+);
+
+// La valeur obtenue est 3, ou undefined si aucun élément ne satisfait le prédicat.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	(number & DNumber.GreaterThan<2>) | undefined,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-findAndReplace.ts

@@ -0,0 +1,35 @@
+/**
+ * @title DArray.findAndReplace
+ *
+ * Remplacer le premier élément satisfaisant un prédicat dans une nouvelle copie, ou retourner undefined.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+const numbers = [1, 2, 3];
+
+// Appel classique : seul le premier élément pair est remplacé.
+const result = DArray.findAndReplace(numbers, DNumber.isEven, 20);
+
+// La valeur obtenue est [1, 20, 3] ; une recherche sans correspondance renverrait undefined.
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[] | undefined, "strict">;
+
+// Appel curifié : le prédicat et la valeur de remplacement sont configurés dans le pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.findAndReplace(DNumber.greaterThan(2), 30),
+);
+
+// La valeur obtenue est [1, 2, 30], ou undefined si la recherche échoue.
+type _CheckPiped = DCommon.ExpectType<typeof piped, readonly number[] | undefined, "strict">;
+
+// Le remplacement conserve la borne maximale, mais la recherche peut échouer.
+declare const constrained: readonly number[] & DArray.MaxElements<4>;
+const constrainedResult = DArray.findAndReplace(constrained, DNumber.greaterThan(1), 0);
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	(readonly number[] & DArray.MaxElements<4>) | undefined,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-findAndSpliceDelete.ts

@@ -0,0 +1,35 @@
+/**
+ * @title DArray.findAndSpliceDelete
+ *
+ * Supprimer plusieurs éléments à partir du premier élément satisfaisant un prédicat.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+const numbers = [1, 2, 3, 4];
+
+// Appel classique : supprimer deux éléments à partir du premier nombre pair.
+const result = DArray.findAndSpliceDelete(numbers, DNumber.isEven, 2);
+
+// La valeur obtenue est [1, 4], ou undefined si aucun élément ne correspond.
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[] | undefined, "strict">;
+
+// Appel curifié : le prédicat et le nombre de suppressions sont configurés dans le pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.findAndSpliceDelete(DNumber.greaterThan(1), 1),
+);
+
+// La valeur obtenue est [1, 3, 4], ou undefined si la recherche échoue.
+type _CheckPiped = DCommon.ExpectType<typeof piped, readonly number[] | undefined, "strict">;
+
+// La suppression conserve une borne maximale existante, avec l’absence si aucun élément ne correspond.
+declare const constrained: readonly number[] & DArray.MaxElements<4>;
+const constrainedResult = DArray.findAndSpliceDelete(constrained, DNumber.greaterThan(1), 1);
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	(readonly number[] & DArray.MaxElements<4>) | undefined,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-findAndSpliceInsert.ts

@@ -0,0 +1,35 @@
+/**
+ * @title DArray.findAndSpliceInsert
+ *
+ * Insérer des éléments avant le premier élément satisfaisant un prédicat.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+const numbers = [1, 3, 4];
+
+// Appel classique : insérer [2] avant le premier élément supérieur à 1.
+const result = DArray.findAndSpliceInsert(numbers, DNumber.greaterThan(1), [2]);
+
+// La valeur obtenue est [1, 2, 3, 4], ou undefined si aucun élément ne correspond.
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[] | undefined, "strict">;
+
+// Appel curifié : le prédicat et les éléments sont configurés dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.findAndSpliceInsert(DCommon.truthy, [3]),
+);
+
+// La valeur obtenue est [3, 1, 3, 4], ou undefined si la recherche échoue.
+type _CheckPiped = DCommon.ExpectType<typeof piped, readonly number[] | undefined, "strict">;
+
+// L’insertion conserve la borne minimale du tableau source, avec l’absence si aucun élément ne correspond.
+declare const constrained: readonly number[] & DArray.MinElements<2>;
+const constrainedResult = DArray.findAndSpliceInsert(constrained, DNumber.greaterThan(1), [0]);
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	(readonly number[] & DArray.MinElements<2>) | undefined,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-findAndSpliceReplace.ts

@@ -0,0 +1,24 @@
+/**
+ * @title DArray.findAndSpliceReplace
+ *
+ * Remplacer la portion commençant au premier élément satisfaisant un prédicat.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const numbers = [1, 2, 3, 4];
+
+// Appel classique : remplacer l’élément 2 par [8, 9].
+const result = DArray.findAndSpliceReplace(numbers, DCommon.equal(2), [8, 9]);
+
+// La valeur obtenue est [1, 8, 9, 3, 4], ou undefined sans correspondance.
+type _CheckResult = DCommon.ExpectType<typeof result, number[] | undefined, "strict">;
+
+// Appel curifié : le prédicat et les nouveaux éléments sont configurés dans le pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.findAndSpliceReplace(DCommon.truthy, [7]),
+);
+
+// La valeur obtenue est [7, 2, 3, 4], ou undefined si la recherche échoue.
+type _CheckPiped = DCommon.ExpectType<typeof piped, number[] | undefined, "strict">;

package/docs/API/10-lang/10-array/10-findDuplicates.ts

@@ -0,0 +1,19 @@
+/**
+ * @title DArray.findDuplicates
+ *
+ * Trouver les valeurs primitives ou temporelles apparaissant plusieurs fois dans un tableau.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+
+const values = ["a", "b", "a", "c", "b"];
+
+// Les valeurs répétées sont retournées une seule fois, dans leur ordre de première répétition.
+const result = DArray.findDuplicates(values);
+
+// La valeur obtenue est ["a", "b"] ; aucun doublon produit undefined.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	undefined | (readonly string[] & DArray.MinElements<1>),
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-findIndex.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DArray.findIndex
+ *
+ * Lire l’index du premier élément satisfaisant un prédicat, ou undefined.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+const numbers = [1, 4, 6];
+
+// Appel classique : l’index du premier nombre pair est retourné.
+const result = DArray.findIndex(numbers, DNumber.isEven);
+
+// La valeur obtenue est 1, ou undefined si aucun élément ne convient.
+type _CheckResult = DCommon.ExpectType<typeof result, number | undefined, "strict">;
+
+// Appel curifié : le prédicat est configuré dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.findIndex(DNumber.greaterThan(5)),
+);
+
+// La valeur obtenue est 2, ou undefined si la recherche échoue.
+type _CheckPiped = DCommon.ExpectType<typeof piped, number | undefined, "strict">;

package/docs/API/10-lang/10-array/10-findLast.ts

@@ -0,0 +1,33 @@
+/**
+ * @title DArray.findLast
+ *
+ * Lire le dernier élément satisfaisant un prédicat, ou undefined si aucun ne convient.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+const numbers = [2, 3, 4, 6];
+
+// Appel classique : la recherche commence à la fin du tableau.
+const result = DArray.findLast(numbers, DNumber.isEven);
+
+// La valeur obtenue est 6, ou undefined si aucun élément ne convient.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	(number & DNumber.Even) | undefined,
+	"strict"
+>;
+
+// Appel curifié : le prédicat est configuré dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.findLast(DNumber.lessThan(4)),
+);
+
+// La valeur obtenue est 3, ou undefined si la recherche échoue.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	(number & DNumber.LessThan<4>) | undefined,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-findLastIndex.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DArray.findLastIndex
+ *
+ * Lire l’index du dernier élément satisfaisant un prédicat, ou undefined.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+const numbers = [2, 3, 4, 6];
+
+// Appel classique : l’index du dernier nombre pair est retourné.
+const result = DArray.findLastIndex(numbers, DNumber.isEven);
+
+// La valeur obtenue est 3, ou undefined si aucun élément ne convient.
+type _CheckResult = DCommon.ExpectType<typeof result, number | undefined, "strict">;
+
+// Appel curifié : le prédicat est configuré dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.findLastIndex(DNumber.lessThan(5)),
+);
+
+// La valeur obtenue est 2, ou undefined si la recherche échoue.
+type _CheckPiped = DCommon.ExpectType<typeof piped, number | undefined, "strict">;

package/docs/API/10-lang/10-array/10-first.ts

@@ -0,0 +1,21 @@
+/**
+ * @title DArray.first
+ *
+ * Lire le premier élément d’un tableau en conservant les garanties de son type.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+
+const values = ["first", "second"];
+
+// La valeur obtenue est "first" ; un tableau sans garantie de cardinalité peut être vide.
+const result = DArray.first(values);
+
+type _CheckResult = DCommon.ExpectType<typeof result, string | undefined, "strict">;
+
+// Une contrainte de cardinalité minimale garantit l’existence du premier élément.
+declare const constrained: readonly string[] & DArray.MinElements<1>;
+const guaranteed = DArray.first(constrained);
+
+// La valeur obtenue est une string sans undefined.
+type _CheckConstrained = DCommon.ExpectType<typeof guaranteed, string, "strict">;

package/docs/API/10-lang/10-array/10-flat.ts

@@ -0,0 +1,22 @@
+/**
+ * @title DArray.flat
+ *
+ * Aplatir les niveaux imbriqués d’un tableau selon une profondeur donnée.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+
+const nested: number[][] = [[1, 2], [3]];
+
+// Appel classique : le premier niveau est aplati par défaut.
+const result = DArray.flat(nested);
+
+// La valeur obtenue est [1, 2, 3].
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[], "strict">;
+
+// Une profondeur explicite aplatit autant de niveaux que demandé.
+const deeplyNested: number[][][] = [[[1], [2]], [[3]]];
+const deepResult = DArray.flat(deeplyNested, 2);
+
+// La valeur obtenue est [1, 2, 3].
+type _CheckDeepResult = DCommon.ExpectType<typeof deepResult, readonly number[], "strict">;

package/docs/API/10-lang/10-array/10-flatMap.ts

@@ -0,0 +1,24 @@
+/**
+ * @title DArray.flatMap
+ *
+ * Transformer chaque élément puis aplatir le niveau de tableau produit.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const numbers = [1, 2, 3];
+
+// Appel classique : chaque nombre produit sa valeur et son double.
+const result = DArray.flatMap(numbers, (value) => [value, value * 2]);
+
+// La valeur obtenue est [1, 2, 2, 4, 3, 6].
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[], "strict">;
+
+// Appel curifié : la transformation est configurée dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.flatMap((value) => [value * 10]),
+);
+
+// La valeur obtenue est [10, 20, 30].
+type _CheckPiped = DCommon.ExpectType<typeof piped, readonly number[], "strict">;

package/docs/API/10-lang/10-array/10-from.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DArray.from
+ *
+ * Convertir une source array-like, itérable ou asynchrone en tableau.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+
+// Une source itérable est matérialisée en tableau synchrone.
+const result = DArray.from(new Set([1, 2, 3]));
+
+// La valeur obtenue est [1, 2, 3].
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[], "strict">;
+
+// Une source asynchrone produit une promesse de tableau.
+async function *values() {
+	await Promise.resolve();
+	yield "a";
+	yield "b";
+}
+
+const asyncResult = DArray.from(values());
+
+// La promesse résout vers ["a", "b"].
+type _CheckAsyncResult = DCommon.ExpectType<typeof asyncResult, Promise<readonly ("a" | "b")[]>, "strict">;

package/docs/API/10-lang/10-array/10-group.ts

@@ -0,0 +1,27 @@
+/**
+ * @title DArray.group
+ *
+ * Regrouper les valeurs produites par une fonction selon un nom de groupe.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+
+const numbers = [1, 2, 3];
+
+// Chaque valeur est affectée à un groupe avec groupOutput via le paramètre output.
+const result = DArray.group(numbers, (value, { output }) => output(
+	value % 2 === 0 ? "even" : "odd",
+	value,
+));
+
+// Les groupes présents contiennent des tuples non vides de leurs valeurs.
+type _CheckEven = DCommon.ExpectType<
+	typeof result.even,
+	readonly [number, ...number[]] | undefined,
+	"strict"
+>;
+type _CheckOdd = DCommon.ExpectType<
+	typeof result.odd,
+	readonly [number, ...number[]] | undefined,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-groupOutput.ts

@@ -0,0 +1,30 @@
+/**
+ * @title DArray.groupOutput
+ *
+ * Construire le résultat nommé attendu par DArray.group pour associer une valeur à un groupe.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+// Appel classique : le nom du groupe et la valeur sont fournis ensemble.
+const result = DArray.groupOutput("numbers", 1);
+
+// La valeur obtenue est { group: "numbers", value: 1 }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	DArray.GroupOutputResult<"numbers", number>,
+	"strict"
+>;
+
+// Appel curifié : le groupe est fixé avant de fournir la valeur.
+const piped = DCommon.pipe(
+	2,
+	DArray.groupOutput("numbers"),
+);
+
+// La valeur obtenue est { group: "numbers", value: 2 }.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	DArray.GroupOutputResult<"numbers", 2>,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-includes.ts

@@ -0,0 +1,24 @@
+/**
+ * @title DArray.includes
+ *
+ * Vérifier qu’un tableau contient une valeur.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const colors: readonly string[] = ["red", "green"];
+
+// Appel classique : la valeur est comparée aux éléments du tableau.
+const result = DArray.includes(colors, "green");
+
+// La valeur obtenue est true.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// Appel curifié : la valeur recherchée est configurée dans l’étape du pipe.
+const piped = DCommon.pipe(
+	colors,
+	DArray.includes("blue"),
+);
+
+// La valeur obtenue est false.
+type _CheckPiped = DCommon.ExpectType<typeof piped, boolean, "strict">;

package/docs/API/10-lang/10-array/10-indexOf.ts

@@ -0,0 +1,24 @@
+/**
+ * @title DArray.indexOf
+ *
+ * Lire l’index de la première occurrence d’une valeur, ou undefined.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const values = ["a", "b", "a"];
+
+// Appel classique : la recherche commence au début par défaut.
+const result = DArray.indexOf(values, "a");
+
+// La valeur obtenue est 0 ; l’absence de correspondance est représentée par undefined.
+type _CheckResult = DCommon.ExpectType<typeof result, number | undefined, "strict">;
+
+// Appel curifié : l’élément recherché est fixé dans l’étape du pipe.
+const piped = DCommon.pipe(
+	values,
+	DArray.indexOf("a"),
+);
+
+// La valeur obtenue est 0.
+type _CheckPiped = DCommon.ExpectType<typeof piped, number | undefined, "strict">;

package/docs/API/10-lang/10-array/10-insert.ts

@@ -0,0 +1,34 @@
+/**
+ * @title DArray.insert
+ *
+ * Ajouter une valeur à la fin d’un tableau dans une nouvelle copie.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const numbers = [1, 2];
+
+// Appel classique : la valeur est ajoutée sans muter le tableau d’origine.
+const result = DArray.insert(3, numbers);
+
+// La valeur obtenue est [1, 2, 3].
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[], "strict">;
+
+// Appel curifié : le tableau est fixé avant de fournir la valeur.
+const piped = DCommon.pipe(
+	3,
+	DArray.insert(numbers),
+);
+
+// La valeur obtenue est [1, 2, 3].
+type _CheckPiped = DCommon.ExpectType<typeof piped, readonly number[], "strict">;
+
+// La contrainte minimale du tableau source est réappliquée après l’ajout.
+declare const constrained: readonly number[] & DArray.MinElements<2>;
+const constrainedResult = DArray.insert(3, constrained);
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	readonly number[] & DArray.MinElements<2>,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-is.ts

@@ -0,0 +1,29 @@
+/**
+ * @title DArray.is
+ *
+ * Vérifier au runtime qu’une valeur est un tableau et affiner son type TypeScript.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DCommon.AnyValue;
+
+// Le test runtime réussit uniquement pour une valeur qui est effectivement un tableau.
+if (DArray.is(input)) {
+	// Dans cette branche, input est affiné en tableau de valeurs inconnues.
+	type _CheckInput = DCommon.ExpectType<typeof input, DCommon.AnyValue[], "strict">;
+}
+
+// Dans un pipe, le même predicate unaire fournit le tableau à l’étape de traitement.
+const first = DCommon.pipe(
+	input,
+	DCommon.when(
+		DArray.is,
+		(array) => {
+			type _CheckArray = DCommon.ExpectType<typeof array, DCommon.AnyValue[], "strict">;
+
+			return DArray.first(array);
+		},
+	),
+);
+type _CheckFirst = DCommon.ExpectType<typeof first, DCommon.AnyValue | undefined, "strict">;