@duplojs/agents-kit 0.1.0-beta.7 → 0.1.0-beta.9

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

@@ -24,7 +24,11 @@ Regrouper les valeurs d’un itérable asynchrone selon les sorties nommées d
  
 ### [DGenerator.asyncLoop](10-asyncLoop.ts)
 
-Produire une séquence asynchrone dans un pipe en distinguant l’arrêt avec ou sans dernière valeur émise.
+Produire une séquence asynchrone en distinguant les valeurs de `next` et celles de la sortie `exit`.
+ 
+### [DGenerator.asyncLoopAccumulator](10-asyncLoopAccumulator.ts)
+
+Produire une séquence asynchrone en mettant à jour un accumulateur à chaque itération.
  
 ### [DGenerator.asyncMap](10-asyncMap.ts)
 
@@ -68,7 +72,15 @@ Construire une sortie nommée destinée à la fonction de regroupement.
  
 ### [DGenerator.loop](10-loop.ts)
 
-Produire une séquence dans un pipe en distinguant l’arrêt avec ou sans dernière valeur émise.
+Produire une séquence synchrone en distinguant les valeurs de `next` et celles de la sortie `exit`.
+ 
+### [DGenerator.loopAccumulator](10-loopAccumulator.ts)
+
+Produire une séquence synchrone en mettant à jour un accumulateur à chaque itération.
+ 
+### [DGenerator.loopAccumulatorFrom](10-loopAccumulatorFrom.ts)
+
+Marquer une valeur initiale pour fixer précisément le type de l’accumulateur d’une boucle.
  
 ### [DGenerator.map](10-map.ts)
 

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

@@ -1,55 +1,102 @@
 /**
  * @title DObject.discriminate
  *
- * Discriminer une union d’objets à partir d’une propriété.
+ * Tester une propriété avec un predicate et affiner l’objet par intersection.
  */
 import * as DObject from "@duplojs/lang/object";
 import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
 
-type Event =
-	| {
-		type: "created";
-		id: string;
-	}
-	| {
-		type: "deleted";
-		id: number;
-	};
-interface CreatedEvent {
-	type: "created";
-	id: string;
-}
-
-interface DeletedEvent {
-	type: "deleted";
+// Le predicate reçoit la valeur de la propriété. S’il affine cette valeur,
+// l’objet conserve son type initial en intersection avec la propriété affinée.
+declare const input: {
+	value: string | number;
 	id: number;
-}
+};
 
-declare const event: Event;
+// Appel classique : affiner une propriété, même sans union d’objets.
+if (DObject.discriminate(input, "value", DCommon.isType("string"))) {
+	type _CheckInput = DCommon.ExpectType<
+		typeof input,
+		{
+			value: string | number;
+			id: number;
+		} & { value: string },
+		"strict"
+	>;
+	const value = input.value;
 
-if (DObject.discriminate(event, "type", "created")) {
-	type _CheckIfEvent = DCommon.ExpectType<typeof event, CreatedEvent, "strict">;
-	const id = event.id;
-	type _CheckIfId = DCommon.ExpectType<typeof id, string, "strict">;
+	type _CheckValue = DCommon.ExpectType<typeof value, string, "strict">;
 }
 
-const result = DObject.discriminate(event, "type", "created");
-
-// Le predicate retourne true pour l’événement created.
-type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
-
-// La forme curifiée est passée directement comme predicate à DCommon.when.
-const id = DCommon.pipe(
-	event,
+// Appel curifié : lire la chaîne si elle est présente, sinon conserver l’objet.
+const result = DCommon.pipe(
+	input,
 	DCommon.when(
-		DObject.discriminate("type", "created"),
-		(createdEvent) => {
-			type _CheckPredicatedInput = DCommon.ExpectType<typeof createdEvent, CreatedEvent, "strict">;
+		DObject.discriminate("value", DCommon.isType("string")),
+		(value) => {
+			type _CheckValue = DCommon.ExpectType<
+				typeof value,
+				{
+					value: string | number;
+					id: number;
+				} & { value: string },
+				"strict"
+			>;
 
-			return createdEvent.id;
+			return value.value;
 		},
 	),
 );
 
-// L’identifiant est une chaîne pour created ; sinon l’événement initial est conservé.
-type _CheckId = DCommon.ExpectType<typeof id, string | DeletedEvent, "strict">;
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	string | {
+		value: string | number;
+		id: number;
+	},
+	"strict"
+>;
+
+// Les contraintes établies par le predicate sont portées par la propriété.
+declare const person: {
+	age: number;
+	name: string;
+};
+
+if (DObject.discriminate(person, "age", DNumber.greaterThan(18))) {
+	type _CheckPerson = DCommon.ExpectType<
+		typeof person,
+		{
+			age: number;
+			name: string;
+		} & { age: number & DNumber.GreaterThan<18> },
+		"strict"
+	>;
+}
+
+// Composer les predicates pour une propriété imbriquée.
+// DCommon.equal permet de conserver une vérification d’égalité.
+declare const account: {
+	profile: { role: string };
+	id: number;
+};
+
+if (DObject.discriminate(account, "profile", DObject.discriminate("role", DCommon.equal("admin")))) {
+	type _CheckAccount = DCommon.ExpectType<
+		typeof account,
+		{
+			profile: { role: string };
+			id: number;
+		} & { profile: { role: string } & { role: "admin" } },
+		"strict"
+	>;
+}
+
+// Un predicate booléen reste accepté, sans affiner l’objet.
+declare const threshold: number;
+
+const isAboveThreshold = DObject.discriminate(person, "age", DNumber.greaterThan(threshold));
+
+// true uniquement si l’âge dépasse le seuil fourni à l’exécution.
+type _CheckIsAboveThreshold = DCommon.ExpectType<typeof isAboveThreshold, boolean, "strict">;

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

@@ -10,17 +10,13 @@ Fusionner les propriétés d’un objet dans une nouvelle valeur.
 
 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é.
+Tester une propriété avec un predicate et affiner l’objet par intersection.
  
 ### [DObject.discriminateEntryKey](10-discriminateEntryKey.ts)
 

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

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

@@ -0,0 +1,36 @@
+/**
+ * @title DSFile.exists
+ *
+ * Vérifier l’accès à une entrée du système de fichiers.
+ */
+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.exists(path);
+
+// Le résultat est un Either : un échec ne signifie pas nécessairement que l’entrée est absente.
+
+// 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-exists-not-found": () => "missing",
+			"file-system-exists-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-exists-not-found
+// file-system-exists-permission-denied
+// file-system-exists-not-directory
+// file-system-exists-too-many-open-files
+// file-system-exists-error

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

@@ -0,0 +1,51 @@
+/**
+ * @title DSFile.link
+ *
+ * Créer un lien physique vers une entrée existante.
+ */
+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.link(source, destination);
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	source,
+	DSFile.link(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-link-not-found": () => "missing",
+			"file-system-link-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-link-not-found
+// file-system-link-permission-denied
+// file-system-link-already-exists
+// file-system-link-not-directory
+// file-system-link-no-space
+// file-system-link-read-only
+// file-system-link-invalid-argument
+// file-system-link-too-many-open-files
+// file-system-link-busy
+// file-system-link-cross-device
+// file-system-link-error

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

@@ -0,0 +1,37 @@
+/**
+ * @title DSFile.linkStat
+ *
+ * Lire les métadonnées d’un lien lui-même.
+ */
+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.linkStat(path);
+
+// Contrairement à stat, cette opération inspecte le lien symbolique lui-même.
+
+// 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-link-stat-not-found": () => "missing",
+			"file-system-link-stat-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-link-stat-not-found
+// file-system-link-stat-permission-denied
+// file-system-link-stat-not-directory
+// file-system-link-stat-too-many-open-files
+// file-system-link-stat-busy
+// file-system-link-stat-error

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

@@ -0,0 +1,41 @@
+/**
+ * @title DSFile.makeDirectory
+ *
+ * Créer un dossier, éventuellement avec ses parents.
+ */
+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.makeDirectory(path, { recursive: true });
+
+// Le Left décrit un éventuel échec de création.
+
+// 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-make-directory-not-found": () => "missing",
+			"file-system-make-directory-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-make-directory-not-found
+// file-system-make-directory-permission-denied
+// file-system-make-directory-already-exists
+// file-system-make-directory-not-directory
+// file-system-make-directory-no-space
+// file-system-make-directory-read-only
+// file-system-make-directory-invalid-argument
+// file-system-make-directory-too-many-open-files
+// file-system-make-directory-busy
+// file-system-make-directory-error