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

package/docs/API/10-lang/10-common/10-asyncLoop.ts

@@ -1,25 +1,23 @@
 /**
  * @title DCommon.asyncLoop
  *
- * Contrôler une boucle asynchrone avec un compteur et une sortie typée.
+ * Répéter une callback asynchrone jusqu’à `exit`, avec un compteur et une valeur de retour typée.
  */
 import * as DCommon from "@duplojs/lang/common";
 
-const result = DCommon.asyncLoop<"done", number>(async({
+const result = DCommon.asyncLoop<"done">(async({
 	count,
-	previousOutput,
 	next,
 	exit,
 }) => {
-	const current = previousOutput ?? 0;
 	await DCommon.timeout();
 
 	if (count === 3) {
 		return exit("done");
 	}
 
-	return next(current + 1);
+	return next();
 });
 
-// La callback est attendue asynchrone, mais conserve les mêmes paramètres que `loop`.
+// La callback est attendue à chaque tour. `next` ne transmet pas d’état à l’itération suivante.
 type _CheckResult = DCommon.ExpectType<typeof result, Promise<"done">, "strict">;

package/docs/API/10-lang/10-common/10-asyncLoopAccumulator.ts

@@ -0,0 +1,40 @@
+/**
+ * @title DCommon.asyncLoopAccumulator
+ *
+ * Répéter une callback asynchrone en faisant circuler un accumulateur et retourner la valeur de `exit`.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const total = await DCommon.asyncLoopAccumulator(0, async({ accumulator, count, next, exit }) => {
+	await DCommon.timeout();
+
+	if (count === 3) {
+		return exit(accumulator);
+	}
+
+	return next(accumulator + count + 1);
+});
+
+// La callback est attendue à chaque tour et le résultat final est celui de `exit`.
+type _CheckTotal = DCommon.ExpectType<typeof total, number, "strict">;
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const structuredTotal = await DCommon.asyncLoopAccumulator(
+	DCommon.loopAccumulatorFrom<Accumulator>({ total: 0 }),
+	async({ accumulator, count, next, exit }) => {
+		await DCommon.timeout();
+
+		return count === 2
+			? exit(accumulator.total)
+			: next({
+				total: accumulator.total + 1,
+				previous: accumulator.total,
+			});
+	},
+);
+
+type _CheckStructuredTotal = DCommon.ExpectType<typeof structuredTotal, number, "strict">;

package/docs/API/10-lang/10-common/10-loop.ts

@@ -1,20 +1,18 @@
 /**
  * @title DCommon.loop
  *
- * Contrôler une boucle synchrone avec un compteur et une sortie typée.
+ * Répéter une callback synchrone jusqu’à `exit`, avec un compteur et une valeur de retour typée.
  */
 import * as DCommon from "@duplojs/lang/common";
 
-const result = DCommon.loop<"done", number>(({ count, previousOutput, next, exit }) => {
-	const current = previousOutput ?? 0;
-
+const result = DCommon.loop<"done">(({ count, next, exit }) => {
 	if (count === 3) {
 		return exit("done");
 	}
 
-	return next(current + 1);
+	return next();
 });
 
-// `count` commence à 0 ; `previousOutput` vaut undefined à la première itération.
-// `next` poursuit la boucle avec une nouvelle sortie, tandis que `exit` la termine.
+// `count` commence à 0. `next()` poursuit la boucle ; les valeurs d'une itération à l'autre
+// doivent être portées par loopAccumulator, car `loop` ne conserve pas les données de `next`.
 type _CheckResult = DCommon.ExpectType<typeof result, "done", "strict">;

package/docs/API/10-lang/10-common/10-loopAccumulator.ts

@@ -0,0 +1,35 @@
+/**
+ * @title DCommon.loopAccumulator
+ *
+ * Répéter une callback synchrone en faisant circuler un accumulateur et retourner la valeur de `exit`.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const total = DCommon.loopAccumulator(0, ({ accumulator, count, next, exit }) => {
+	if (count === 3) {
+		return exit(accumulator);
+	}
+
+	return next(accumulator + count + 1);
+});
+
+// Le nombre initial est élargi en number ; chaque `next` fournit l’accumulateur du tour suivant.
+type _CheckTotal = DCommon.ExpectType<typeof total, number, "strict">;
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const structuredTotal = DCommon.loopAccumulator(
+	DCommon.loopAccumulatorFrom<Accumulator>({ total: 0 }),
+	({ accumulator, count, next, exit }) => count === 2
+		? exit(accumulator.total)
+		: next({
+			total: accumulator.total + 1,
+			previous: accumulator.total,
+		}),
+);
+
+// `loopAccumulatorFrom` conserve le type choisi pour un accumulateur structuré.
+type _CheckStructuredTotal = DCommon.ExpectType<typeof structuredTotal, number, "strict">;

package/docs/API/10-lang/10-common/10-loopAccumulatorFrom.ts

@@ -0,0 +1,29 @@
+/**
+ * @title DCommon.loopAccumulatorFrom
+ *
+ * Marquer une valeur initiale pour fixer précisément le type de l’accumulateur d’une boucle.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const initialAccumulator = DCommon.loopAccumulatorFrom<Accumulator>({ total: 0 });
+
+type _CheckInitialAccumulator = DCommon.ExpectType<
+	typeof initialAccumulator,
+	DCommon.LoopAccumulatorFromResult<Accumulator>,
+	"strict"
+>;
+
+const result = DCommon.loopAccumulator(initialAccumulator, ({ accumulator, count, next, exit }) => count === 2
+	? exit(accumulator.total)
+	: next({
+		total: accumulator.total + 1,
+		previous: accumulator.total,
+	}));
+
+// La boucle reçoit Accumulator comme état et retourne le nombre fourni à `exit`.
+type _CheckResult = DCommon.ExpectType<typeof result, number, "strict">;

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

@@ -16,7 +16,11 @@ Construire une fonction qui enchaîne des opérations synchrones ou asynchrones.
  
 ### [DCommon.asyncLoop](10-asyncLoop.ts)
 
-Contrôler une boucle asynchrone avec un compteur et une sortie typée.
+Répéter une callback asynchrone jusqu’à `exit`, avec un compteur et une valeur de retour typée.
+ 
+### [DCommon.asyncLoopAccumulator](10-asyncLoopAccumulator.ts)
+
+Répéter une callback asynchrone en faisant circuler un accumulateur et retourner la valeur de `exit`.
  
 ### [DCommon.asyncPipe](10-asyncPipe.ts)
 
@@ -120,7 +124,15 @@ Fournir une valeur déjà calculée à une étape de pipe sans écrire de callba
  
 ### [DCommon.loop](10-loop.ts)
 
-Contrôler une boucle synchrone avec un compteur et une sortie typée.
+Répéter une callback synchrone jusqu’à `exit`, avec un compteur et une valeur de retour typée.
+ 
+### [DCommon.loopAccumulator](10-loopAccumulator.ts)
+
+Répéter une callback synchrone en faisant circuler un accumulateur et retourner la valeur de `exit`.
+ 
+### [DCommon.loopAccumulatorFrom](10-loopAccumulatorFrom.ts)
+
+Marquer une valeur initiale pour fixer précisément le type de l’accumulateur d’une boucle.
  
 ### [DCommon.memo](10-memo.ts)
 

package/docs/API/10-lang/10-generator/10-asyncLoop.ts

@@ -1,57 +1,48 @@
 /**
  * @title DGenerator.asyncLoop
  *
- * 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`.
  */
 import * as DArray from "@duplojs/lang/array";
 import * as DCommon from "@duplojs/lang/common";
 import * as DGenerator from "@duplojs/lang/generator";
-import * as DNumber from "@duplojs/lang/number";
 
-// Arrêt sans dernière valeur : `exit()` termine la boucle asynchrone sans émettre d’élément supplémentaire.
+// La callback peut être asynchrone ; `count` est le seul état fourni à chaque tour.
 const withoutExitValue = DCommon.pipe(
-	DGenerator.asyncLoop(async({ previousOutput, next, exit }: DGenerator.LoopParams<number>) => {
+	DGenerator.asyncLoop(async({ count, next, exit }: DGenerator.LoopParams<number>) => {
 		await DCommon.timeout();
 
-		if (previousOutput === 3) {
+		if (count === 3) {
 			return exit();
 		}
 
-		return next(
-			previousOutput === undefined
-				? 1
-				: DNumber.sum([previousOutput, 1]),
-		);
+		return next(count + 1);
 	}),
 	DArray.from,
 );
 
-// La promesse se résout vers [1, 2, 3] : `exit()` n’émet aucune dernière valeur.
+// La promesse se résout vers [1, 2, 3] : `exit()` termine sans ajouter de valeur.
 type _CheckWithoutExitValue = DCommon.ExpectType<
 	typeof withoutExitValue,
 	Promise<readonly number[]>,
 	"strict"
 >;
 
-// Arrêt avec dernière valeur : `exit("done")` termine la boucle en l’émettant.
+// La callback est attendue à chaque tour ; les sorties sont émises avant l’appel du tour suivant.
 const withExitValue = DCommon.pipe(
-	DGenerator.asyncLoop(async({ previousOutput, next, exit }: DGenerator.LoopParams<number>) => {
+	DGenerator.asyncLoop(async({ count, next, exit }: DGenerator.LoopParams<number | "done">) => {
 		await DCommon.timeout();
 
-		if (previousOutput === 3) {
+		if (count === 3) {
 			return exit("done");
 		}
 
-		return next(
-			previousOutput === undefined
-				? 1
-				: DNumber.sum([previousOutput, 1]),
-		);
+		return next(count + 1);
 	}),
 	DArray.from,
 );
 
-// La promesse se résout vers [1, 2, 3, "done"] : la valeur de `exit` est émise comme dernier élément.
+// La promesse se résout vers [1, 2, 3, "done"] : `exit` ajoute sa valeur en dernier.
 type _CheckWithExitValue = DCommon.ExpectType<
 	typeof withExitValue,
 	Promise<readonly (number | "done")[]>,

package/docs/API/10-lang/10-generator/10-asyncLoopAccumulator.ts

@@ -0,0 +1,40 @@
+/**
+ * @title DGenerator.asyncLoopAccumulator
+ *
+ * Produire une séquence asynchrone en mettant à jour un accumulateur à chaque itération.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+const values = await DArray.from(DGenerator.asyncLoopAccumulator(0, async({ accumulator, count, next, exit }) => {
+	await DCommon.timeout();
+
+	return count === 3
+		? exit(Promise.resolve(accumulator))
+		: next(accumulator + 1, Promise.resolve(accumulator));
+}));
+
+// La callback et les valeurs émises peuvent être asynchrones ; les sorties sont résolues avant émission.
+type _CheckValues = DCommon.ExpectType<typeof values, readonly number[], "strict">;
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const finalTotal = await DArray.from(DGenerator.asyncLoopAccumulator(
+	DGenerator.loopAccumulatorFrom<Accumulator>({ total: 0 }),
+	async({ accumulator, count, next, exit }) => {
+		await DCommon.timeout();
+
+		return count === 2
+			? exit(Promise.resolve(accumulator.total))
+			: next({
+				total: accumulator.total + 1,
+				previous: accumulator.total,
+			}, Promise.resolve(accumulator.total));
+	},
+));
+
+type _CheckFinalTotal = DCommon.ExpectType<typeof finalTotal, readonly number[], "strict">;

package/docs/API/10-lang/10-generator/10-loop.ts

@@ -1,53 +1,44 @@
 /**
  * @title DGenerator.loop
  *
- * 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`.
  */
 import * as DArray from "@duplojs/lang/array";
 import * as DCommon from "@duplojs/lang/common";
 import * as DGenerator from "@duplojs/lang/generator";
-import * as DNumber from "@duplojs/lang/number";
 
-// Arrêt sans dernière valeur : `exit()` termine la boucle sans émettre d’élément supplémentaire.
+// `count` est le seul état fourni à chaque tour ; `next` émet des valeurs et continue.
 const withoutExitValue = DCommon.pipe(
-	DGenerator.loop(({ previousOutput, next, exit }: DGenerator.LoopParams<number>) => {
-		if (previousOutput === 3) {
+	DGenerator.loop(({ count, next, exit }: DGenerator.LoopParams<number>) => {
+		if (count === 3) {
 			return exit();
 		}
 
-		return next(
-			previousOutput === undefined
-				? 1
-				: DNumber.sum([previousOutput, 1]),
-		);
+		return next(count + 1);
 	}),
 	DArray.from,
 );
 
-// La sortie vaut [1, 2, 3] : `next` émet les valeurs intermédiaires, mais `exit()` n’en émet aucune.
+// La sortie vaut [1, 2, 3] : `exit()` termine sans ajouter de valeur.
 type _CheckWithoutExitValue = DCommon.ExpectType<
 	typeof withoutExitValue,
 	readonly number[],
 	"strict"
 >;
 
-// Arrêt avec dernière valeur : `exit(value)` termine la boucle en émettant cette valeur.
+// `exit(value)` termine la boucle et émet sa valeur après celles émises par `next`.
 const withExitValue = DCommon.pipe(
-	DGenerator.loop(({ previousOutput, next, exit }: DGenerator.LoopParams<number>) => {
-		if (previousOutput === 3) {
+	DGenerator.loop(({ count, next, exit }: DGenerator.LoopParams<number>) => {
+		if (count === 3) {
 			return exit(4);
 		}
 
-		return next(
-			previousOutput === undefined
-				? 1
-				: DNumber.sum([previousOutput, 1]),
-		);
+		return next(count + 1);
 	}),
 	DArray.from,
 );
 
-// La sortie vaut [1, 2, 3, 4] : `exit(4)` ajoute la dernière valeur à la séquence.
+// La sortie vaut [1, 2, 3, 4] : les valeurs multiples de `next` et `exit` forment la séquence.
 type _CheckWithExitValue = DCommon.ExpectType<
 	typeof withExitValue,
 	readonly number[],

package/docs/API/10-lang/10-generator/10-loopAccumulator.ts

@@ -0,0 +1,33 @@
+/**
+ * @title DGenerator.loopAccumulator
+ *
+ * Produire une séquence synchrone en mettant à jour un accumulateur à chaque itération.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+const values = DArray.from(DGenerator.loopAccumulator(0, ({ accumulator, count, next, exit }) => count === 3
+	? exit(accumulator)
+	: next(accumulator + 1, accumulator)));
+
+// `next` reçoit d’abord le nouvel accumulateur, puis émet les valeurs suivantes.
+// La valeur de `exit` est également émise avant que le générateur se termine.
+type _CheckValues = DCommon.ExpectType<typeof values, readonly number[], "strict">;
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const finalTotal = DArray.from(DGenerator.loopAccumulator(
+	DGenerator.loopAccumulatorFrom<Accumulator>({ total: 0 }),
+	({ accumulator, count, next, exit }) => count === 2
+		? exit(accumulator.total)
+		: next({
+			total: accumulator.total + 1,
+			previous: accumulator.total,
+		}, accumulator.total),
+));
+
+type _CheckFinalTotal = DCommon.ExpectType<typeof finalTotal, readonly number[], "strict">;

package/docs/API/10-lang/10-generator/10-loopAccumulatorFrom.ts

@@ -0,0 +1,30 @@
+/**
+ * @title DGenerator.loopAccumulatorFrom
+ *
+ * Marquer une valeur initiale pour fixer précisément le type de l’accumulateur d’une boucle.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const initialAccumulator = DGenerator.loopAccumulatorFrom<Accumulator>({ total: 0 });
+
+type _CheckInitialAccumulator = DCommon.ExpectType<
+	typeof initialAccumulator,
+	DGenerator.LoopAccumulatorFromResult<Accumulator>,
+	"strict"
+>;
+
+const result = DGenerator.loopAccumulator(initialAccumulator, ({ accumulator, count, next, exit }) => count === 2
+	? exit(accumulator.total)
+	: next({
+		total: accumulator.total + 1,
+		previous: accumulator.total,
+	}, accumulator.total));
+
+// La boucle reçoit Accumulator comme état, tout en produisant sa valeur de sortie dans le générateur.
+type _CheckResult = DCommon.ExpectType<typeof result, Generator<number, unknown, unknown>, "strict">;

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/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();