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

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

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * @title DSFile.truncate
+ *
+ * Tronquer ou étendre un fichier à une taille en octets.
+ */
+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.truncate(path, 128);
+
+// Le résultat indique si la modification 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-truncate-not-found": () => "missing",
+			"file-system-truncate-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-truncate-not-found
+// file-system-truncate-permission-denied
+// file-system-truncate-is-directory
+// file-system-truncate-not-directory
+// file-system-truncate-no-space
+// file-system-truncate-read-only
+// file-system-truncate-invalid-argument
+// file-system-truncate-too-many-open-files
+// file-system-truncate-busy
+// file-system-truncate-error

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

@@ -0,0 +1,75 @@
+/**
+ * @title DSFile.walkDirectory
+ *
+ * Parcourir les entrées d’un dossier sous forme d’interfaces.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DGenerator from "@duplojs/lang/generator";
+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.walkDirectory(
+	directory,
+	{ recursive: true },
+);
+
+if (DEither.isRight(result)) {
+	const entries = DEither.unwrapRight(result);
+
+	// Le générateur produit des interfaces munies d'un chemin absolu.
+	// Le test du kind permet d'utiliser les opérations propres aux fichiers.
+	const descriptions = DArray.from(
+		DGenerator.map(
+			entries,
+			(entry) => {
+				type _CheckPath = DCommon.ExpectType<
+					typeof entry.path,
+					string & DPath.Path & DPath.Absolute,
+					"strict"
+				>;
+
+				if (DSFile.isFileInterface(entry)) {
+					return {
+						path: entry.path,
+						mimeType: entry.getMimeType(),
+					};
+				}
+
+				if (DSFile.isFolderInterface(entry)) {
+					return {
+						path: entry.path,
+						name: entry.getName(),
+					};
+				}
+
+				// Une entrée inconnue conserve notamment path et stat().
+				return { path: entry.path };
+			},
+		),
+	);
+} else {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-walk-directory-not-found": () => "missing-directory",
+			"file-system-walk-directory-permission-denied": () => "access-denied",
+			"file-system-walk-directory-not-directory": () => "not-a-directory",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-walk-directory-not-found
+// file-system-walk-directory-permission-denied
+// file-system-walk-directory-not-directory
+// file-system-walk-directory-too-many-open-files
+// file-system-walk-directory-busy
+// file-system-walk-directory-error

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

@@ -0,0 +1,50 @@
+/**
+ * @title DSFile.writeFile
+ *
+ * Écrire des octets dans 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.writeFile(path, bytes);
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	path,
+	DSFile.writeFile(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-write-file-not-found": () => "missing",
+			"file-system-write-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-write-file-not-found
+// file-system-write-file-permission-denied
+// file-system-write-file-is-directory
+// file-system-write-file-not-directory
+// file-system-write-file-no-space
+// file-system-write-file-read-only
+// file-system-write-file-invalid-argument
+// file-system-write-file-too-many-open-files
+// file-system-write-file-busy
+// file-system-write-file-error

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

@@ -0,0 +1,41 @@
+/**
+ * @title DSFile.writeJsonFile
+ *
+ * Sérialiser une valeur en JSON et l’écrire dans 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.writeJsonFile(path, { enabled: true });
+
+// Le résultat peut signaler une erreur de sérialisation ou d’é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-write-json-file-not-found": () => "missing",
+			"file-system-write-json-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-write-json-file-not-found
+// file-system-write-json-file-permission-denied
+// file-system-write-json-file-is-directory
+// file-system-write-json-file-not-directory
+// file-system-write-json-file-no-space
+// file-system-write-json-file-read-only
+// file-system-write-json-file-invalid-argument
+// file-system-write-json-file-too-many-open-files
+// file-system-write-json-file-busy
+// file-system-write-json-file-error

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

@@ -0,0 +1,49 @@
+/**
+ * @title DSFile.writeTextFile
+ *
+ * Écrire du texte dans 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.writeTextFile(path, "configuration");
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	path,
+	DSFile.writeTextFile("configuration"),
+);
+
+// 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-write-text-file-not-found": () => "missing",
+			"file-system-write-text-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-write-text-file-not-found
+// file-system-write-text-file-permission-denied
+// file-system-write-text-file-is-directory
+// file-system-write-text-file-not-directory
+// file-system-write-text-file-no-space
+// file-system-write-text-file-read-only
+// file-system-write-text-file-invalid-argument
+// file-system-write-text-file-too-many-open-files
+// file-system-write-text-file-busy
+// file-system-write-text-file-error