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

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

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

@@ -0,0 +1,35 @@
+/**
+ * @title DSFile.makeTemporaryDirectory
+ *
+ * Créer un dossier temporaire avec un préfixe.
+ */
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+const result = await DSFile.makeTemporaryDirectory("export-");
+
+// La position et le nom obtenus dépendent du runtime et du préfixe.
+
+// 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-temporary-directory-permission-denied": () => "access-denied",
+			"file-system-make-temporary-directory-no-space": () => "no-space",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-make-temporary-directory-permission-denied
+// file-system-make-temporary-directory-not-directory
+// file-system-make-temporary-directory-no-space
+// file-system-make-temporary-directory-read-only
+// file-system-make-temporary-directory-invalid-argument
+// file-system-make-temporary-directory-too-many-open-files
+// file-system-make-temporary-directory-error

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

@@ -0,0 +1,40 @@
+/**
+ * @title DSFile.makeTemporaryFile
+ *
+ * Créer un fichier temporaire avec préfixe et suffixe.
+ */
+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 prefix: string & DPath.Segment;
+declare const suffix: string & DPath.Segment;
+
+const result = await DSFile.makeTemporaryFile(prefix, suffix);
+
+// Le Right porte le chemin créé ; le Left porte l’erreur 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-temporary-file-permission-denied": () => "access-denied",
+			"file-system-make-temporary-file-already-exists": () => "already-exists",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-make-temporary-file-permission-denied
+// file-system-make-temporary-file-already-exists
+// file-system-make-temporary-file-not-directory
+// file-system-make-temporary-file-no-space
+// file-system-make-temporary-file-read-only
+// file-system-make-temporary-file-invalid-argument
+// file-system-make-temporary-file-too-many-open-files
+// file-system-make-temporary-file-error

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

@@ -0,0 +1,51 @@
+/**
+ * @title DSFile.move
+ *
+ * Déplacer une ressource vers un chemin de destination.
+ */
+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.move(source, destination);
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	source,
+	DSFile.move(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-move-not-found": () => "missing",
+			"file-system-move-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-move-not-found
+// file-system-move-permission-denied
+// file-system-move-already-exists
+// file-system-move-is-directory
+// file-system-move-not-directory
+// file-system-move-directory-not-empty
+// file-system-move-read-only
+// file-system-move-invalid-argument
+// file-system-move-busy
+// file-system-move-cross-device
+// file-system-move-error

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

@@ -0,0 +1,52 @@
+/**
+ * @title DSFile.readDirectory
+ *
+ * Lister les chemins d’un dossier avec récursivité et résolution absolue optionnelles.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DPath from "@duplojs/lang/path";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DSFile from "@duplojs/server/file";
+
+declare const directory: string & DPath.Path;
+
+const result = await DSFile.readDirectory(
+	directory,
+	{
+		recursive: true,
+		absolute: true,
+	},
+);
+
+if (DEither.isRight(result)) {
+	const paths = DEither.unwrapRight(result);
+
+	type _CheckPaths = DCommon.ExpectType<
+		typeof paths,
+		readonly (string & DPath.Path & DPath.Absolute)[],
+		"strict"
+	>;
+} else {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-read-directory-not-found": () => "missing-directory",
+			"file-system-read-directory-permission-denied": () => "access-denied",
+			"file-system-read-directory-not-directory": () => "not-a-directory",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Sans absolute, les chemins sont relatifs au dossier lu.
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-read-directory-not-found
+// file-system-read-directory-permission-denied
+// file-system-read-directory-not-directory
+// file-system-read-directory-too-many-open-files
+// file-system-read-directory-busy
+// file-system-read-directory-error

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

@@ -0,0 +1,38 @@
+/**
+ * @title DSFile.readFile
+ *
+ * Lire les octets d’un fichier.
+ */
+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.readFile(path);
+
+// Le Right porte les octets lus ; le Left décrit l’échec d’accès.
+
+// 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-read-file-not-found": () => "missing",
+			"file-system-read-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-read-file-not-found
+// file-system-read-file-permission-denied
+// file-system-read-file-is-directory
+// file-system-read-file-not-directory
+// file-system-read-file-too-many-open-files
+// file-system-read-file-busy
+// file-system-read-file-error

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

@@ -0,0 +1,38 @@
+/**
+ * @title DSFile.readJsonFile
+ *
+ * Lire et analyser un fichier JSON.
+ */
+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.readJsonFile(path);
+
+// Le JSON obtenu doit encore être validé selon le contrat applicatif.
+
+// 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-read-json-file-not-found": () => "missing",
+			"file-system-read-json-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-read-json-file-not-found
+// file-system-read-json-file-permission-denied
+// file-system-read-json-file-is-directory
+// file-system-read-json-file-not-directory
+// file-system-read-json-file-too-many-open-files
+// file-system-read-json-file-busy
+// file-system-read-json-file-error

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

@@ -0,0 +1,37 @@
+/**
+ * @title DSFile.readLink
+ *
+ * Lire la cible d’un lien symbolique.
+ */
+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.readLink(path);
+
+// Le résultat dépend de la cible enregistrée sur le système de fichiers.
+
+// 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-read-link-not-found": () => "missing",
+			"file-system-read-link-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-read-link-not-found
+// file-system-read-link-permission-denied
+// file-system-read-link-invalid-argument
+// file-system-read-link-not-directory
+// file-system-read-link-too-many-open-files
+// file-system-read-link-error

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

@@ -0,0 +1,38 @@
+/**
+ * @title DSFile.readTextFile
+ *
+ * Lire le contenu UTF-8 d'un fichier et distinguer les erreurs d'accès.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DSFile from "@duplojs/server/file";
+
+declare const configurationPath: string & DPath.Path;
+
+const result = await DSFile.readTextFile(configurationPath);
+
+if (DEither.isRight(result)) {
+	// Le contenu dépend du fichier au moment de la lecture.
+	const text = DEither.unwrapRight(result);
+} else {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-read-text-file-not-found": () => "missing-configuration",
+			"file-system-read-text-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-read-text-file-not-found
+// file-system-read-text-file-permission-denied
+// file-system-read-text-file-is-directory
+// file-system-read-text-file-not-directory
+// file-system-read-text-file-too-many-open-files
+// file-system-read-text-file-busy
+// file-system-read-text-file-error

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

@@ -0,0 +1,36 @@
+/**
+ * @title DSFile.realPath
+ *
+ * Résoudre le chemin réel d’une entrée.
+ */
+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.realPath(path);
+
+// Le résultat dépend de l’état du système de fichiers et des liens.
+
+// 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-real-path-not-found": () => "missing",
+			"file-system-real-path-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-real-path-not-found
+// file-system-real-path-permission-denied
+// file-system-real-path-not-directory
+// file-system-real-path-too-many-open-files
+// file-system-real-path-error