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

package/docs/API/10-lang/10-object/10-pick.ts

@@ -0,0 +1,41 @@
+/**
+ * @title DObject.pick
+ *
+ * Créer un objet avec les propriétés sélectionnées.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+const source = {
+	name: "Duplo",
+	version: 1,
+	active: true,
+};
+const result = DObject.pick(source, ["name", "active"]);
+
+// La valeur obtenue est { name: "Duplo", active: true }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		name: string;
+		active: boolean;
+	},
+	"strict"
+>;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.pick({
+		name: true,
+		version: false,
+	}),
+);
+
+// Une sélection par objet de drapeaux conserve seulement name.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		name: string;
+	},
+	"strict"
+>;

package/docs/API/10-lang/10-object/10-to.ts

@@ -0,0 +1,40 @@
+/**
+ * @title DObject.to
+ *
+ * Construire un nouvel objet en appliquant une forme de transformations à une même entrée.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+import type * as DNumber from "@duplojs/lang/number";
+import * as DString from "@duplojs/lang/string";
+
+const result = DObject.to("Duplo", {
+	upper: DString.toUpperCase,
+	length: DString.length,
+});
+
+// La valeur obtenue est { upper: "DUPLO", length: 5 }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		upper: Uppercase<string>;
+		length: number & DNumber.Positive;
+	},
+	"strict"
+>;
+
+const piped = DCommon.pipe(
+	"AgentKit",
+	DObject.to({
+		upper: DString.toUpperCase,
+	}),
+);
+
+// La forme curifiée applique la forme au texte reçu par le pipe.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		upper: "AGENTKIT";
+	},
+	"strict"
+>;

package/docs/API/10-lang/10-object/10-transformProperties.ts

@@ -0,0 +1,43 @@
+/**
+ * @title DObject.transformProperties
+ *
+ * Transformer plusieurs propriétés d’un objet en conservant les autres.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const source = {
+	name: "duplo",
+	version: 1,
+};
+const result = DObject.transformProperties(source, {
+	name: DString.toUpperCase,
+});
+
+// La valeur obtenue est { name: "DUPLO", version: 1 }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		name: Uppercase<string>;
+		version: number;
+	},
+	"strict"
+>;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.transformProperties({
+		name: DString.toUpperCase,
+	}),
+);
+
+// La forme curifiée place la description des transformations dans l’étape du pipe.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		name: Uppercase<string>;
+		version: number;
+	},
+	"strict"
+>;

package/docs/API/10-lang/10-object/10-transformProperty.ts

@@ -0,0 +1,39 @@
+/**
+ * @title DObject.transformProperty
+ *
+ * Transformer une propriété précise d’un objet.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const source = {
+	name: "duplo",
+	version: 1,
+};
+const result = DObject.transformProperty(source, "name", DString.toUpperCase);
+
+// La valeur obtenue est { name: "DUPLO", version: 1 }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		name: Uppercase<string>;
+		version: number;
+	},
+	"strict"
+>;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.transformProperty("name", DString.toUpperCase),
+);
+
+// La forme curifiée ne remplace que la propriété ciblée.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		name: Uppercase<string>;
+		version: number;
+	},
+	"strict"
+>;

package/docs/API/10-lang/10-object/10-values.ts

@@ -0,0 +1,19 @@
+/**
+ * @title DObject.values
+ *
+ * Extraire les valeurs d’un objet avec l’union des types de ses propriétés.
+ */
+import * as DObject from "@duplojs/lang/object";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DObject.values({
+	name: "Duplo",
+	version: 1,
+});
+
+// La valeur obtenue est ["Duplo", 1] et son type contient string | number.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	readonly (string | number)[],
+	"strict"
+>;

package/docs/API/10-lang/10-object/index.llms.md

@@ -0,0 +1,92 @@
+## DObject
+
+Fonctions fonctionnelles pour lire, discriminer, transformer, fusionner et reconstruire des objets en conservant les informations de typage utiles.
+
+### [DObject.assign](10-assign.ts)
+
+Fusionner les propriétés d’un objet dans une nouvelle valeur.
+ 
+### [DObject.countKeys](10-countKeys.ts)
+
+Compter les clés runtime d’un objet.
+ 
+### [DObject.deepDiscriminate](10-deepDiscriminate.ts)
+
+Discriminer une union d’objets à partir d’une propriété imbriquée.
+ 
+### [DObject.deepOverride](10-deepOverride.ts)
+
+Remplacer récursivement les valeurs définies d’un objet sans modifier la source.
+ 
+### [DObject.discriminate](10-discriminate.ts)
+
+Discriminer une union d’objets à partir d’une propriété.
+ 
+### [DObject.discriminateEntryKey](10-discriminateEntryKey.ts)
+
+Tester ou affiner une entrée selon sa clé.
+ 
+### [DObject.discriminateEntryValue](10-discriminateEntryValue.ts)
+
+Tester ou affiner une entrée selon sa valeur.
+ 
+### [DObject.entries](10-entries.ts)
+
+Convertir les propriétés d’un objet en entrées typées.
+ 
+### [DObject.entry](10-entry.ts)
+
+Construire une entrée objet en conservant les types de sa clé et de sa valeur.
+ 
+### [DObject.fromEntries](10-fromEntries.ts)
+
+Reconstruire un objet typé à partir d’une collection d’entrées.
+ 
+### [DObject.getDeepProperty](10-getDeepProperty.ts)
+
+Lire une propriété imbriquée avec un chemin vérifié par TypeScript.
+ 
+### [DObject.getProperty](10-getProperty.ts)
+
+Lire une propriété d’un objet en conservant son type.
+ 
+### [DObject.hasKeys](10-hasKeys.ts)
+
+Vérifier la présence de propriétés définies et affiner leur caractère obligatoire.
+ 
+### [DObject.isSimple](10-isSimple.ts)
+
+Vérifier si un objet est simple sans affiner son type.
+ 
+### [DObject.keys](10-keys.ts)
+
+Lister les clés d’un objet avec un type correspondant à ses propriétés.
+ 
+### [DObject.omit](10-omit.ts)
+
+Créer un objet en retirant les propriétés sélectionnées.
+ 
+### [DObject.override](10-override.ts)
+
+Remplacer les propriétés définies d’un objet par de nouvelles valeurs.
+ 
+### [DObject.pick](10-pick.ts)
+
+Créer un objet avec les propriétés sélectionnées.
+ 
+### [DObject.to](10-to.ts)
+
+Construire un nouvel objet en appliquant une forme de transformations à une même entrée.
+ 
+### [DObject.transformProperties](10-transformProperties.ts)
+
+Transformer plusieurs propriétés d’un objet en conservant les autres.
+ 
+### [DObject.transformProperty](10-transformProperty.ts)
+
+Transformer une propriété précise d’un objet.
+ 
+### [DObject.values](10-values.ts)
+
+Extraire les valeurs d’un objet avec l’union des types de ses propriétés.
+ 

package/docs/API/10-lang/10-object/index.md

@@ -0,0 +1,3 @@
+## DObject
+
+Fonctions fonctionnelles pour lire, discriminer, transformer, fusionner et reconstruire des objets en conservant les informations de typage utiles.

package/docs/API/10-lang/10-path/10-computeRelative.ts

@@ -0,0 +1,19 @@
+/**
+ * @title DPath.computeRelative
+ *
+ * Calculer le chemin relatif entre deux chemins absolus.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const source = DPath.declareAbsolutePath("/workspace/src");
+const destination = DPath.declareAbsolutePath("/workspace/test/index.ts");
+const result = DPath.computeRelative(source, destination);
+
+// Le chemin obtenu est ../test/index.ts.
+type _CheckResult = DCommon.ExpectType<typeof result, string & DPath.Path, "strict">;
+
+// Une même origine et destination donnent le chemin courant.
+const same = DPath.computeRelative(source, source);
+// La valeur obtenue est ".". Aucun accès au système de fichiers n’est effectué.
+type _CheckSame = DCommon.ExpectType<typeof same, string & DPath.Path, "strict">;

package/docs/API/10-lang/10-path/10-concatSegment.ts

@@ -0,0 +1,28 @@
+/**
+ * @title DPath.concatSegment
+ *
+ * Assembler un segment avec un ou plusieurs autres segments.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const fileName = DPath.declareSegment("file");
+const extension = DPath.declareSegment(".ts");
+
+// L’appel direct assemble deux segments.
+const result = DPath.concatSegment(fileName, extension);
+// La valeur obtenue est file.ts.
+type _CheckResult = DCommon.ExpectType<typeof result, string & DPath.Segment, "strict">;
+
+// La forme curifiée configure le segment ajouté avant de recevoir le segment de base.
+const curriedResult = DCommon.pipe(
+	fileName,
+	DPath.concatSegment(extension),
+);
+// La valeur obtenue est également file.ts.
+type _CheckCurriedResult = DCommon.ExpectType<typeof curriedResult, string & DPath.Segment, "strict">;
+
+// Plusieurs morceaux : concatSegment n’insère aucun séparateur.
+const testFile = DPath.concatSegment(fileName, DPath.declareSegment(".test"), extension);
+// La valeur obtenue est file.test.ts ; seule la contrainte Segment est conservée.
+type _CheckTestFile = DCommon.ExpectType<typeof testFile, string & DPath.Segment, "strict">;

package/docs/API/10-lang/10-path/10-create.ts

@@ -0,0 +1,21 @@
+/**
+ * @title DPath.create
+ *
+ * Normaliser une chaîne et retourner un Either selon qu’elle forme un chemin valide.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import * as DPath from "@duplojs/lang/path";
+
+const result = DPath.create("src//module/../index.ts");
+// Le Right contient src/index.ts ; un chemin invalide produit un Left contenant l’entrée.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	DEither.Success<string & DPath.Path> | DEither.Error<string>,
+	"strict"
+>;
+
+// Refus : un caractère nul ne produit pas le chemin demandé.
+const rejected = DPath.create("invalid\0path");
+// Error contient la chaîne d’origine, sans normalisation de sa valeur d’erreur.
+type _CheckRejected = DCommon.ExpectType<typeof rejected, DEither.Success<string & DPath.Path> | DEither.Error<string>, "strict">;

package/docs/API/10-lang/10-path/10-createAbsolute.ts

@@ -0,0 +1,21 @@
+/**
+ * @title DPath.createAbsolute
+ *
+ * Normaliser une chaîne et vérifier qu’elle représente un chemin absolu.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import * as DPath from "@duplojs/lang/path";
+
+const result = DPath.createAbsolute("/workspace/src/../index.ts");
+// Le Right contient /workspace/index.ts ; un chemin relatif produit un Left.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	DEither.Success<string & DPath.Absolute & DPath.Path> | DEither.Error<string>,
+	"strict"
+>;
+
+// Refus : un chemin relatif ne produit pas le chemin demandé.
+const rejected = DPath.createAbsolute("src/index.ts");
+// Error contient la chaîne d’origine, sans normalisation de sa valeur d’erreur.
+type _CheckRejected = DCommon.ExpectType<typeof rejected, DEither.Success<string & DPath.Absolute & DPath.Path> | DEither.Error<string>, "strict">;

package/docs/API/10-lang/10-path/10-createAbsoluteOrThrow.ts

@@ -0,0 +1,16 @@
+/**
+ * @title DPath.createAbsoluteOrThrow
+ *
+ * Normaliser un chemin absolu ou lever une erreur si l’entrée est invalide.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+// À la frontière d’exécution, choisir cette variante pour interrompre le programme
+// sur un chemin invalide. Dans un traitement réutilisable, préférer createAbsolute.
+const result = DPath.createAbsoluteOrThrow("/workspace/src/../index.ts");
+// La valeur obtenue est /workspace/index.ts.
+type _CheckResult = DCommon.ExpectType<typeof result, string & DPath.Absolute & DPath.Path, "strict">;
+
+// Une entrée comme "src/index.ts" lève DPath.CreateAbsolutePathError,
+// dont la propriété value conserve la chaîne d’origine.

package/docs/API/10-lang/10-path/10-createMatcher.ts

@@ -0,0 +1,50 @@
+/**
+ * @title DPath.createMatcher
+ *
+ * Créer un predicate de chemin à partir de motifs glob positifs et négatifs.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const matcher = DPath.createMatcher(["*.ts", "!dist"]);
+type _CheckMatcher = DCommon.ExpectType<typeof matcher, DPath.PathMatcher, "strict">;
+const sourceFile = DPath.declarePath("src/index.ts");
+const result = matcher(sourceFile);
+// Le résultat vaut true : le chemin correspond au motif TypeScript et n’est pas exclu.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+const excludedFile = matcher(DPath.declarePath("dist/index.ts"));
+// Le résultat vaut false : le motif négatif exclut le dossier dist.
+type _CheckExcludedFile = DCommon.ExpectType<typeof excludedFile, boolean, "strict">;
+
+// Un motif seul est accepté ; * reste dans un segment, ** final traverse les dossiers.
+const nestedMatcher = DPath.createMatcher("src/**");
+const nested = nestedMatcher(DPath.declarePath("src/deep/index.ts"));
+// La valeur obtenue est true.
+type _CheckNested = DCommon.ExpectType<typeof nested, boolean, "strict">;
+
+// Il faut au moins une règle positive ; les exclusions gagnent quel que soit leur ordre.
+const onlyExclusions = DPath.createMatcher(["!dist"]);
+const unselected = onlyExclusions(sourceFile);
+// La valeur obtenue est false : aucune règle positive ne sélectionne sourceFile.
+type _CheckUnselected = DCommon.ExpectType<typeof unselected, boolean, "strict">;
+
+// Utiliser le matcher comme predicate booléen sur des chemins déjà valides.
+declare const candidate: DPath.AnyPath;
+if (matcher(candidate)) {
+	// Le matcher ne raffine pas le type du chemin et ne consulte pas le disque.
+	type _CheckCandidate = DCommon.ExpectType<typeof candidate, DPath.AnyPath, "strict">;
+	const name = DPath.getBaseName(candidate);
+	type _CheckName = DCommon.ExpectType<typeof name, (string & DPath.Segment & DPath.Path) | null, "strict">;
+}
+
+const selectedName = DCommon.pipe(
+	candidate,
+	DCommon.when(matcher, DPath.getBaseName),
+);
+// Un chemin correspondant donne son nom ; les autres restent inchangés.
+type _CheckSelectedName = DCommon.ExpectType<
+	typeof selectedName,
+	(string & DPath.Segment & DPath.Path) | null | DPath.AnyPath,
+	"strict"
+>;

package/docs/API/10-lang/10-path/10-createOrThrow.ts

@@ -0,0 +1,16 @@
+/**
+ * @title DPath.createOrThrow
+ *
+ * Normaliser un chemin ou lever une erreur si l’entrée est invalide.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+// À la frontière d’exécution, choisir cette variante pour interrompre le programme
+// sur un chemin invalide. Dans un traitement réutilisable, préférer create.
+const result = DPath.createOrThrow("src//module/../index.ts");
+// La valeur obtenue est src/index.ts.
+type _CheckResult = DCommon.ExpectType<typeof result, string & DPath.Path, "strict">;
+
+// Une entrée comme "invalid\0path" lève DPath.CreatePathError,
+// dont la propriété value conserve la chaîne d’origine.

package/docs/API/10-lang/10-path/10-createSegment.ts

@@ -0,0 +1,26 @@
+/**
+ * @title DPath.createSegment
+ *
+ * Normaliser une chaîne et vérifier qu’elle ne contient qu’un segment.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import * as DPath from "@duplojs/lang/path";
+
+const result = DPath.createSegment("index.ts");
+// Le Right contient index.ts. La validation porte sur le résultat de la normalisation.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	DEither.Success<string & DPath.Segment & DPath.Path> | DEither.Error<string>,
+	"strict"
+>;
+
+// Normaliser avant de valider : un chemin composé peut devenir un segment unique.
+const normalized = DPath.createSegment("src/../index.ts");
+// Success contient index.ts, même si l’entrée contenait des séparateurs.
+type _CheckNormalized = DCommon.ExpectType<typeof normalized, DEither.Success<string & DPath.Segment & DPath.Path> | DEither.Error<string>, "strict">;
+
+// Refus : après normalisation, src/index.ts contient encore deux segments.
+const rejected = DPath.createSegment("src/index.ts");
+// Error contient l’entrée originale src/index.ts. "", "." et ".." sont aussi refusés.
+type _CheckRejected = DCommon.ExpectType<typeof rejected, DEither.Success<string & DPath.Segment & DPath.Path> | DEither.Error<string>, "strict">;

package/docs/API/10-lang/10-path/10-createSegmentOrThrow.ts

@@ -0,0 +1,16 @@
+/**
+ * @title DPath.createSegmentOrThrow
+ *
+ * Normaliser un segment ou lever une erreur si l’entrée n’est pas un segment valide.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+// À la frontière d’exécution, choisir cette variante pour interrompre le programme
+// sur un chemin invalide. Dans un traitement réutilisable, préférer createSegment.
+const result = DPath.createSegmentOrThrow("index.ts");
+// La valeur obtenue est index.ts.
+type _CheckResult = DCommon.ExpectType<typeof result, string & DPath.Segment & DPath.Path, "strict">;
+
+// Une entrée comme "src/index.ts" lève DPath.CreateSegmentPathError,
+// dont la propriété value conserve la chaîne d’origine.

package/docs/API/10-lang/10-path/10-declareAbsolutePath.ts

@@ -0,0 +1,15 @@
+/**
+ * @title DPath.declareAbsolutePath
+ *
+ * Déclarer un littéral de chemin comme chemin absolu après vérification statique.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const path = DPath.declareAbsolutePath("/workspace/src/index.ts");
+// Le littéral conserve sa valeur et reçoit les contraintes Absolute et Path.
+type _CheckPath = DCommon.ExpectType<typeof path, "/workspace/src/index.ts" & DPath.Absolute & DPath.Path, "strict">;
+
+// La déclaration ne normalise ni ne valide au runtime ; elle exige un littéral valide.
+// @ts-expect-error Le littéral ne satisfait pas le contrat de cette déclaration.
+DPath.declareAbsolutePath("src/index.ts");

package/docs/API/10-lang/10-path/10-declarePath.ts

@@ -0,0 +1,15 @@
+/**
+ * @title DPath.declarePath
+ *
+ * Déclarer un littéral valide comme chemin après vérification statique.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const path = DPath.declarePath("src/index.ts");
+// Le littéral conserve sa valeur et reçoit la contrainte Path.
+type _CheckPath = DCommon.ExpectType<typeof path, "src/index.ts" & DPath.Path, "strict">;
+
+// La déclaration ne normalise ni ne valide au runtime ; elle exige un littéral valide.
+// @ts-expect-error Le littéral ne satisfait pas le contrat de cette déclaration.
+DPath.declarePath("src//index.ts");

package/docs/API/10-lang/10-path/10-declareSegment.ts

@@ -0,0 +1,15 @@
+/**
+ * @title DPath.declareSegment
+ *
+ * Déclarer un littéral valide comme segment après vérification statique.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const segment = DPath.declareSegment("index.ts");
+// Le littéral conserve sa valeur et reçoit les contraintes Segment et Path.
+type _CheckSegment = DCommon.ExpectType<typeof segment, "index.ts" & DPath.Segment & DPath.Path, "strict">;
+
+// La déclaration ne normalise ni ne valide au runtime ; elle exige un littéral valide.
+// @ts-expect-error Le littéral ne satisfait pas le contrat de cette déclaration.
+DPath.declareSegment("src/index.ts");

package/docs/API/10-lang/10-path/10-getBaseName.ts

@@ -0,0 +1,22 @@
+/**
+ * @title DPath.getBaseName
+ *
+ * Lire le dernier segment d’un chemin, avec la possibilité d’en retirer l’extension.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const path = DPath.declarePath("src/index.test.ts");
+const result = DPath.getBaseName(path, { removeExtension: true });
+// La valeur obtenue est index.test ; null indique un chemin sans nom de base.
+type _CheckResult = DCommon.ExpectType<typeof result, (string & DPath.Segment & DPath.Path) | null, "strict">;
+
+// Sans option, le nom conserve toutes ses extensions.
+const fullName = DPath.getBaseName(path);
+// La valeur obtenue est index.test.ts.
+type _CheckFullName = DCommon.ExpectType<typeof fullName, (string & DPath.Segment & DPath.Path) | null, "strict">;
+
+// La racine ne possède pas de dernier segment.
+const rootName = DPath.getBaseName(DPath.declareAbsolutePath("/"));
+// La valeur obtenue est null ; le type de retour reste l’union générale.
+type _CheckRootName = DCommon.ExpectType<typeof rootName, (string & DPath.Segment & DPath.Path) | null, "strict">;

package/docs/API/10-lang/10-path/10-getExtensionName.ts

@@ -0,0 +1,22 @@
+/**
+ * @title DPath.getExtensionName
+ *
+ * Lire l’extension du dernier segment, avec la possibilité de conserver le point.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const path = DPath.declarePath("src/index.test.ts");
+const result = DPath.getExtensionName(path, { withDot: true });
+// La valeur obtenue est .ts ; null indique l’absence d’extension.
+type _CheckResult = DCommon.ExpectType<typeof result, (string & DPath.Segment & DPath.Path) | null, "strict">;
+
+// Sans option, seul le suffixe après le dernier point est retourné.
+const extension = DPath.getExtensionName(path);
+// La valeur obtenue est ts.
+type _CheckExtension = DCommon.ExpectType<typeof extension, (string & DPath.Segment & DPath.Path) | null, "strict">;
+
+// Un nom caché sans autre point n’a pas d’extension.
+const hiddenFile = DPath.getExtensionName(DPath.declareSegment(".env"));
+// La valeur obtenue est null.
+type _CheckHiddenFile = DCommon.ExpectType<typeof hiddenFile, (string & DPath.Segment & DPath.Path) | null, "strict">;

package/docs/API/10-lang/10-path/10-getParentFolderPath.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DPath.getParentFolderPath
+ *
+ * Lire le dossier parent d’un chemin en conservant son caractère absolu lorsqu’il est connu.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const path = DPath.declareAbsolutePath("/workspace/src/index.ts");
+const result = DPath.getParentFolderPath(path);
+// La valeur obtenue est /workspace/src.
+type _CheckResult = DCommon.ExpectType<typeof result, (string & DPath.Path & DPath.Absolute) | null, "strict">;
+
+// Avec un chemin relatif, le résultat ne porte pas Absolute.
+const relativeParent = DPath.getParentFolderPath(DPath.declarePath("src/index.ts"));
+// La valeur obtenue est src.
+type _CheckRelativeParent = DCommon.ExpectType<typeof relativeParent, (string & DPath.Path) | null, "strict">;
+
+// La racine n’a pas de parent ; un nom isolé a pour parent le chemin courant.
+const rootParent = DPath.getParentFolderPath(DPath.declareAbsolutePath("/"));
+// La valeur obtenue est null.
+type _CheckRootParent = DCommon.ExpectType<typeof rootParent, (string & DPath.Path & DPath.Absolute) | null, "strict">;
+const localParent = DPath.getParentFolderPath(DPath.declareSegment("index.ts"));
+// La valeur obtenue est ".".
+type _CheckLocalParent = DCommon.ExpectType<typeof localParent, (string & DPath.Path) | null, "strict">;