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

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

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

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

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

@@ -0,0 +1,40 @@
+/**
+ * @title DSFile.remove
+ *
+ * Supprimer une entrée, éventuellement récursivement.
+ */
+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.remove(path, { recursive: true });
+
+// Le résultat doit être traité même si une vérification préalable a réussi.
+
+// 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-remove-not-found": () => "missing",
+			"file-system-remove-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-remove-not-found
+// file-system-remove-permission-denied
+// file-system-remove-is-directory
+// file-system-remove-not-directory
+// file-system-remove-directory-not-empty
+// file-system-remove-read-only
+// file-system-remove-invalid-argument
+// file-system-remove-busy
+// file-system-remove-error

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

@@ -0,0 +1,43 @@
+/**
+ * @title DSFile.rename
+ *
+ * Renommer une entrée dans son dossier parent.
+ */
+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 name: string & DPath.Segment;
+
+const result = await DSFile.rename(path, name);
+
+// Le résultat porte le nouveau chemin en cas de succè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-rename-not-found": () => "missing",
+			"file-system-rename-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-rename-not-found
+// file-system-rename-permission-denied
+// file-system-rename-already-exists
+// file-system-rename-is-directory
+// file-system-rename-not-directory
+// file-system-rename-directory-not-empty
+// file-system-rename-read-only
+// file-system-rename-invalid-argument
+// file-system-rename-busy
+// file-system-rename-cross-device
+// file-system-rename-error

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

@@ -0,0 +1,37 @@
+/**
+ * @title DSFile.setMode
+ *
+ * Modifier les permissions 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.setMode(path, 0o640);
+
+// Le résultat peut notamment signaler un refus 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-set-mode-not-found": () => "missing",
+			"file-system-set-mode-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-set-mode-not-found
+// file-system-set-mode-permission-denied
+// file-system-set-mode-not-directory
+// file-system-set-mode-read-only
+// file-system-set-mode-invalid-argument
+// file-system-set-mode-error

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

@@ -0,0 +1,38 @@
+/**
+ * @title DSFile.setOwner
+ *
+ * Modifier le propriétaire et le groupe 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;
+declare const owner: DSFile.SetOwnerParams;
+
+const result = await DSFile.setOwner(path, owner);
+
+// La disponibilité et les permissions dépendent de l’environnement.
+
+// 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-set-owner-not-found": () => "missing",
+			"file-system-set-owner-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-set-owner-not-found
+// file-system-set-owner-permission-denied
+// file-system-set-owner-not-directory
+// file-system-set-owner-read-only
+// file-system-set-owner-invalid-argument
+// file-system-set-owner-error

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

@@ -0,0 +1,42 @@
+/**
+ * @title DSFile.setTime
+ *
+ * Modifier les dates d’accès et de modification d’une entrée.
+ */
+import type * as DChrono from "@duplojs/lang/chrono";
+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 date: DChrono.TheDate;
+
+const result = await DSFile.setTime(path, {
+	accessTime: date,
+	modifiedTime: date,
+});
+
+// Le résultat indique si les métadonnées ont été modifiées.
+
+// 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-set-time-not-found": () => "missing",
+			"file-system-set-time-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-set-time-not-found
+// file-system-set-time-permission-denied
+// file-system-set-time-not-directory
+// file-system-set-time-read-only
+// file-system-set-time-invalid-argument
+// file-system-set-time-error

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

@@ -0,0 +1,37 @@
+/**
+ * @title DSFile.stat
+ *
+ * Lire les métadonnées 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.stat(path);
+
+// Le Right décrit notamment la nature, la taille et les dates de l’entrée.
+
+// 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-stat-not-found": () => "missing",
+			"file-system-stat-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-stat-not-found
+// file-system-stat-permission-denied
+// file-system-stat-not-directory
+// file-system-stat-too-many-open-files
+// file-system-stat-busy
+// file-system-stat-error