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

package/docs/API/10-lang/10-string/10-uncapitalize.ts

@@ -0,0 +1,17 @@
+/**
+ * @title DString.uncapitalize
+ *
+ * Mettre en minuscule le premier caractère d'une chaîne.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const result = DString.uncapitalize("Duplo");
+// La valeur obtenue est "duplo".
+type _CheckResult = DCommon.ExpectType<typeof result, "duplo", "strict">;
+
+const piped = DCommon.pipe(
+	"Duplo",
+	DString.uncapitalize,
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "duplo", "strict">;

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

@@ -0,0 +1,208 @@
+## DString
+
+Fonctions de manipulation, recherche, validation et transformation des chaînes de caractères, avec des formes curifiées et des contraintes de typage lorsque l'API peut les établir.
+
+### [DString.at](10-at.ts)
+
+Lire le caractère situé à un index, avec `undefined` lorsque l'index est hors limites.
+ 
+### [DString.capitalize](10-capitalize.ts)
+
+Mettre en majuscule le premier caractère d'une chaîne.
+ 
+### [DString.charAt](10-charAt.ts)
+
+Lire le caractère situé à un index positif ou nul.
+ 
+### [DString.concat](10-concat.ts)
+
+Ajouter une ou plusieurs chaînes à la fin d'une chaîne.
+ 
+### [DString.endsWith](10-endsWith.ts)
+
+Tester si une chaîne se termine par une sous-chaîne.
+ 
+### [DString.extract](10-extract.ts)
+
+Extraire la première occurrence d'un motif avec ses groupes et sa position.
+ 
+### [DString.extractAll](10-extractAll.ts)
+
+Produire les occurrences d'un motif global sous forme de génératrice.
+ 
+### [DString.first](10-first.ts)
+
+Lire le premier caractère d'une chaîne.
+ 
+### [DString.includes](10-includes.ts)
+
+Tester si une chaîne contient une sous-chaîne.
+ 
+### [DString.indexOf](10-indexOf.ts)
+
+Retourner la position d'une sous-chaîne, ou `undefined` si elle est absente.
+ 
+### [DString.isComposedOf](10-isComposedOf.ts)
+
+Vérifier qu'une chaîne ne contient que des caractères appartenant à une ou plusieurs plages.
+ 
+### [DString.isEmail](10-isEmail.ts)
+
+Vérifier qu'une chaîne respecte le format d'une adresse e-mail.
+ 
+### [DString.isIn](10-isIn.ts)
+
+Vérifier qu'une chaîne appartient à une collection de valeurs autorisées.
+ 
+### [DString.isKeyof](10-isKeyof.ts)
+
+Vérifier qu'une valeur est une clé de l'objet fourni et affiner son type.
+ 
+### [DString.isNotEmpty](10-isNotEmpty.ts)
+
+Vérifier qu'une chaîne contient au moins un caractère.
+ 
+### [DString.isNumber](10-isNumber.ts)
+
+Vérifier qu'une chaîne représente un nombre et établir cette contrainte dans le type.
+ 
+### [DString.isTrimmed](10-isTrimmed.ts)
+
+Vérifier qu'une chaîne ne possède pas d'espace superflu à ses extrémités.
+ 
+### [DString.isUrl](10-isUrl.ts)
+
+Vérifier qu'une chaîne est une URL valide.
+ 
+### [DString.isUuid](10-isUuid.ts)
+
+Vérifier qu'une chaîne respecte le format UUID pris en charge.
+ 
+### [DString.join](10-join.ts)
+
+Réunir les chaînes d'une collection avec un séparateur.
+ 
+### [DString.last](10-last.ts)
+
+Lire le dernier caractère d'une chaîne.
+ 
+### [DString.lastIndexOf](10-lastIndexOf.ts)
+
+Retourner la dernière position d'une sous-chaîne, ou `undefined` si elle est absente.
+ 
+### [DString.length](10-length.ts)
+
+Retourner le nombre de caractères d'une chaîne.
+ 
+### [DString.lengthEqual](10-lengthEqual.ts)
+
+Tester ou établir qu'une chaîne possède exactement un nombre donné de caractères.
+ 
+### [DString.maxCharacters](10-maxCharacters.ts)
+
+Tester ou établir une longueur maximale pour une chaîne.
+ 
+### [DString.minCharacters](10-minCharacters.ts)
+
+Tester ou établir une longueur minimale pour une chaîne.
+ 
+### [DString.normalize](10-normalize.ts)
+
+Normaliser une chaîne selon une forme Unicode.
+ 
+### [DString.padEnd](10-padEnd.ts)
+
+Compléter une chaîne par la droite jusqu'à une longueur cible.
+ 
+### [DString.padStart](10-padStart.ts)
+
+Compléter une chaîne par la gauche jusqu'à une longueur cible.
+ 
+### [DString.pop](10-pop.ts)
+
+Retirer le dernier caractère d'une chaîne.
+ 
+### [DString.prepend](10-prepend.ts)
+
+Ajouter une ou plusieurs chaînes au début d'une chaîne.
+ 
+### [DString.repeat](10-repeat.ts)
+
+Répéter une chaîne un nombre positif de fois.
+ 
+### [DString.replace](10-replace.ts)
+
+Remplacer la première occurrence d'un motif par une chaîne ou une fonction de remplacement.
+ 
+### [DString.replaceAll](10-replaceAll.ts)
+
+Remplacer toutes les occurrences d'un motif par une chaîne ou une fonction de remplacement.
+ 
+### [DString.search](10-search.ts)
+
+Retourner la position d'un motif, ou `undefined` lorsqu'il ne correspond pas.
+ 
+### [DString.shift](10-shift.ts)
+
+Retirer le premier caractère d'une chaîne.
+ 
+### [DString.slice](10-slice.ts)
+
+Extraire une portion d'une chaîne entre deux index.
+ 
+### [DString.sort](10-sort.ts)
+
+Trier une copie d'une collection de chaînes dans l'ordre croissant ou décroissant.
+ 
+### [DString.sortCompare](10-sortCompare.ts)
+
+Comparer deux chaînes avec l'ordre de tri du domaine String.
+ 
+### [DString.split](10-split.ts)
+
+Découper une chaîne selon un séparateur, avec une limite facultative.
+ 
+### [DString.startsWith](10-startsWith.ts)
+
+Tester si une chaîne commence par une sous-chaîne.
+ 
+### [DString.stringify](10-stringify.ts)
+
+Convertir une valeur quelconque en représentation textuelle sans laisser `undefined` au résultat.
+ 
+### [DString.substring](10-substring.ts)
+
+Extraire une sous-chaîne selon les règles de `substring`.
+ 
+### [DString.test](10-test.ts)
+
+Tester une chaîne avec une expression régulière.
+ 
+### [DString.to](10-to.ts)
+
+Convertir une valeur stringifiable en chaîne en conservant les littéraux connus lorsque c'est possible.
+ 
+### [DString.toLowerCase](10-toLowerCase.ts)
+
+Convertir une chaîne en minuscules.
+ 
+### [DString.toUpperCase](10-toUpperCase.ts)
+
+Convertir une chaîne en majuscules.
+ 
+### [DString.trim](10-trim.ts)
+
+Supprimer les espaces au début et à la fin d'une chaîne.
+ 
+### [DString.trimEnd](10-trimEnd.ts)
+
+Supprimer les espaces à la fin d'une chaîne.
+ 
+### [DString.trimStart](10-trimStart.ts)
+
+Supprimer les espaces au début d'une chaîne.
+ 
+### [DString.uncapitalize](10-uncapitalize.ts)
+
+Mettre en minuscule le premier caractère d'une chaîne.
+ 

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

@@ -0,0 +1,3 @@
+## DString
+
+Fonctions de manipulation, recherche, validation et transformation des chaînes de caractères, avec des formes curifiées et des contraintes de typage lorsque l'API peut les établir.

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

@@ -0,0 +1,50 @@
+/**
+ * @title DTuple.from
+ *
+ * Interpréter les contraintes de cardinalité d’un tableau comme une forme tuple.
+ */
+import type * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DTuple from "@duplojs/lang/tuple";
+
+// Sans contrainte de cardinalité, la source reste un tableau de longueur inconnue.
+declare const values: readonly string[];
+const array = DTuple.from(values);
+type _CheckArray = DCommon.ExpectType<typeof array, readonly string[], "strict">;
+
+// Une longueur exacte établit le nombre de positions du tuple.
+declare const fixedValues: readonly string[] & DArray.LengthEqual<3>;
+const fixedTuple = DTuple.from(fixedValues);
+type _CheckFixedTuple = DCommon.ExpectType<
+	typeof fixedTuple,
+	readonly [string, string, string],
+	"strict"
+>;
+
+// Un minimum d’éléments garantit les premières positions et laisse la suite variable.
+declare const nonEmptyValues: readonly string[] & DArray.MinElements<2>;
+const nonEmptyTuple = DTuple.from(nonEmptyValues);
+type _CheckNonEmptyTuple = DCommon.ExpectType<
+	typeof nonEmptyTuple,
+	readonly [string, string, ...string[]],
+	"strict"
+>;
+
+// Ces conversions sont statiques : à l’exécution, from renvoie la même source.
+
+// Borne maximale seule : elle ne garantit aucune position présente.
+declare const boundedValues: readonly string[] & DArray.MaxElements<4>;
+const bounded = DTuple.from(boundedValues);
+// La source et sa contrainte restent inchangées.
+type _CheckBounded = DCommon.ExpectType<typeof bounded, readonly string[] & DArray.MaxElements<4>, "strict">;
+
+// Combinaison : les positions minimales et la borne maximale sont conservées.
+declare const rangedValues: readonly string[] & DArray.MinElements<2> & DArray.MaxElements<4>;
+const ranged = DTuple.from(rangedValues);
+type _CheckRanged = DCommon.ExpectType<typeof ranged, readonly [string, string, ...string[]] & DArray.MaxElements<4>, "strict">;
+
+// Un tuple déjà précis est reconstruit à partir de son union d’éléments.
+declare const pair: readonly ["name", 1];
+const rebuilt = DTuple.from(pair);
+// Même valeur et même référence, mais les types propres à chaque position sont perdus.
+type _CheckRebuilt = DCommon.ExpectType<typeof rebuilt, readonly [1 | "name", 1 | "name"], "strict">;

package/docs/API/10-lang/10-tuple/10-map.ts

@@ -0,0 +1,37 @@
+/**
+ * @title DTuple.map
+ *
+ * Transformer chaque élément d’un tuple en conservant sa cardinalité.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+import * as DTuple from "@duplojs/lang/tuple";
+
+// L’index de chaque élément est disponible dans le contexte du callback.
+const positions = DTuple.map(
+	["draft", "ready"],
+	(_value, { index }) => index,
+);
+// La valeur obtenue est [0, 1].
+type _CheckPositions = DCommon.ExpectType<typeof positions, readonly [number, number], "strict">;
+
+// La forme curifiée transforme les éléments dans un pipe, avant de les réunir.
+declare const states: readonly ["draft", "ready"];
+const key = DCommon.pipe(
+	states,
+	DTuple.map(DString.toUpperCase),
+	DString.join("-"),
+);
+// La valeur obtenue est "DRAFT-READY".
+// Le type conservateur combine toutes les chaînes produites pour chaque position.
+type _CheckKey = DCommon.ExpectType<
+	typeof key,
+	"DRAFT-DRAFT" | "DRAFT-READY" | "READY-DRAFT" | "READY-READY",
+	"strict"
+>;
+
+// Tuple à reste variable : le premier élément reste garanti après transformation.
+declare const names: readonly [string, ...string[]];
+const upperNames = DTuple.map(names, DString.toUpperCase);
+// Chaque nom est converti en majuscules ; au moins une position est conservée.
+type _CheckUpperNames = DCommon.ExpectType<typeof upperNames, readonly [Uppercase<string>, ...Uppercase<string>[]], "strict">;

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

@@ -0,0 +1,12 @@
+## DTuple
+
+Manipulation et typage des tuples : convertir les garanties de cardinalité en positions typées, puis transformer leurs éléments en conservant leur forme.
+
+### [DTuple.from](10-from.ts)
+
+Interpréter les contraintes de cardinalité d’un tableau comme une forme tuple.
+ 
+### [DTuple.map](10-map.ts)
+
+Transformer chaque élément d’un tuple en conservant sa cardinalité.
+ 

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

@@ -0,0 +1,3 @@
+## DTuple
+
+Manipulation et typage des tuples : convertir les garanties de cardinalité en positions typées, puis transformer leurs éléments en conservant leur forme.

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

@@ -0,0 +1,3 @@
+# @duplojs/lang
+
+Primitives fonctionnelles indépendantes de la plateforme pour composer des transformations, manipuler les données et préserver leurs garanties de typage.

package/docs/API/20-server/10-file/10-appendFile.ts

@@ -0,0 +1,50 @@
+/**
+ * @title DSFile.appendFile
+ *
+ * Ajouter des octets à un fichier.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+declare const bytes: Uint8Array;
+
+// Appel direct
+const result = await DSFile.appendFile(path, bytes);
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	path,
+	DSFile.appendFile(bytes),
+);
+
+// Chaque résultat indique la réussite ou l'échec de l'écriture.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-append-file-not-found": () => "missing",
+			"file-system-append-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-append-file-not-found
+// file-system-append-file-permission-denied
+// file-system-append-file-is-directory
+// file-system-append-file-not-directory
+// file-system-append-file-no-space
+// file-system-append-file-read-only
+// file-system-append-file-invalid-argument
+// file-system-append-file-too-many-open-files
+// file-system-append-file-busy
+// file-system-append-file-error

package/docs/API/20-server/10-file/10-appendTextFile.ts

@@ -0,0 +1,49 @@
+/**
+ * @title DSFile.appendTextFile
+ *
+ * Ajouter du texte à un fichier.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+
+// Appel direct
+const result = await DSFile.appendTextFile(path, "nouvelle ligne\n");
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	path,
+	DSFile.appendTextFile("nouvelle ligne\n"),
+);
+
+// Chaque résultat indique la réussite ou l'échec de l'écriture.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-append-text-file-not-found": () => "missing",
+			"file-system-append-text-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-append-text-file-not-found
+// file-system-append-text-file-permission-denied
+// file-system-append-text-file-is-directory
+// file-system-append-text-file-not-directory
+// file-system-append-text-file-no-space
+// file-system-append-text-file-read-only
+// file-system-append-text-file-invalid-argument
+// file-system-append-text-file-too-many-open-files
+// file-system-append-text-file-busy
+// file-system-append-text-file-error

package/docs/API/20-server/10-file/10-copy.ts

@@ -0,0 +1,50 @@
+/**
+ * @title DSFile.copy
+ *
+ * Copier une ressource, récursivement pour un dossier.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const source: string & DPath.Path;
+declare const destination: string & DPath.Path;
+
+// Appel direct
+const result = await DSFile.copy(source, destination);
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	source,
+	DSFile.copy(destination),
+);
+
+// Les résultats dépendent de l'état du système de fichiers et peuvent échouer.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-copy-not-found": () => "missing",
+			"file-system-copy-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-copy-not-found
+// file-system-copy-permission-denied
+// file-system-copy-already-exists
+// file-system-copy-not-directory
+// file-system-copy-no-space
+// file-system-copy-read-only
+// file-system-copy-invalid-argument
+// file-system-copy-too-many-open-files
+// file-system-copy-busy
+// file-system-copy-error

package/docs/API/20-server/10-file/10-createEntryInterface.ts

@@ -0,0 +1,13 @@
+/**
+ * @title DSFile.createEntryInterface
+ *
+ * Inspecter une entrée et construire son interface adaptée.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+
+declare const path: string & DPath.Path;
+
+const result = await DSFile.createEntryInterface(path);
+
+// La réussite distingue fichier, dossier et entrée inconnue ; un échec porte l’erreur d’inspection.

package/docs/API/20-server/10-file/10-createFileInterface.ts

@@ -0,0 +1,22 @@
+/**
+ * @title DSFile.createFileInterface
+ *
+ * Construire une référence de fichier sans accès au disque.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+
+declare const path: string & DPath.Path;
+
+const entry = DSFile.createFileInterface(path);
+
+// La construction ne vérifie ni l’existence ni la nature de la ressource.
+
+// Les méthodes de référence extraient les composants sans accès au disque.
+const name = entry.getName();
+const mimeType = entry.getMimeType();
+
+// stat, exists et les opérations de déplacement consultent le système.
+// rename, move et relocate retournent une nouvelle interface en cas de succès ;
+// ils ne modifient pas le chemin de cette référence.
+const metadata = await entry.stat();

package/docs/API/20-server/10-file/10-createFolderInterface.ts

@@ -0,0 +1,20 @@
+/**
+ * @title DSFile.createFolderInterface
+ *
+ * Construire une référence de dossier sans accès au disque.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+
+declare const path: string & DPath.Path;
+
+const entry = DSFile.createFolderInterface(path);
+
+// La construction ne vérifie ni l’existence ni la nature de la ressource.
+
+// Ces méthodes consultent le système de fichiers et retournent un Either.
+const children = await entry.getChildren();
+const traversal = await entry.walk({ recursive: true });
+
+// Un déplacement ou renommage réussi retourne une nouvelle interface ;
+// la référence initiale conserve son ancien chemin.

package/docs/API/20-server/10-file/10-createUnknownEntryInterface.ts

@@ -0,0 +1,13 @@
+/**
+ * @title DSFile.createUnknownEntryInterface
+ *
+ * Construire une référence d’entrée de type inconnu sans accès au disque.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+
+declare const path: string & DPath.Path;
+
+const entry = DSFile.createUnknownEntryInterface(path);
+
+// La construction ne vérifie ni l’existence ni la nature de la ressource.

package/docs/API/20-server/10-file/10-ensureDirectory.ts

@@ -0,0 +1,39 @@
+/**
+ * @title DSFile.ensureDirectory
+ *
+ * Créer un dossier et ses parents si nécessaire.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+
+const result = await DSFile.ensureDirectory(path);
+
+// La réussite confirme que le dossier a été assuré.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-ensure-directory-permission-denied": () => "access-denied",
+			"file-system-ensure-directory-no-space": () => "no-space",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-ensure-directory-permission-denied
+// file-system-ensure-directory-not-directory
+// file-system-ensure-directory-no-space
+// file-system-ensure-directory-read-only
+// file-system-ensure-directory-invalid-argument
+// file-system-ensure-directory-too-many-open-files
+// file-system-ensure-directory-busy
+// file-system-ensure-directory-error

package/docs/API/20-server/10-file/10-ensureFile.ts

@@ -0,0 +1,40 @@
+/**
+ * @title DSFile.ensureFile
+ *
+ * Créer un fichier absent sans tronquer un fichier existant.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+
+const result = await DSFile.ensureFile(path);
+
+// Le dossier parent doit déjà exister.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-ensure-file-permission-denied": () => "access-denied",
+			"file-system-ensure-file-no-space": () => "no-space",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-ensure-file-permission-denied
+// file-system-ensure-file-is-directory
+// file-system-ensure-file-not-directory
+// file-system-ensure-file-no-space
+// file-system-ensure-file-read-only
+// file-system-ensure-file-invalid-argument
+// file-system-ensure-file-too-many-open-files
+// file-system-ensure-file-busy
+// file-system-ensure-file-error