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

package/README.md

@@ -14,18 +14,26 @@ Read the relevant pages by resolving their links relative to the summary. Before
 
 Use each API domain's `index.llms.md` to find a public function by its exported namespace and name, such as `DArray.map` in [`docs/API/10-lang/10-array/index.llms.md`](docs/API/10-lang/10-array/index.llms.md). The other current domains are [Chrono](docs/API/10-lang/10-chrono/index.llms.md), [Common](docs/API/10-lang/10-common/index.llms.md), [DataStructure](docs/API/10-lang/10-dataStructure/index.llms.md), [Either](docs/API/10-lang/10-either/index.llms.md), and [Generator](docs/API/10-lang/10-generator/index.llms.md). API sources are primarily TypeScript files combining descriptions and typed usage examples. Each summary exposes their headers and links to those files.
 
-The `install-skill` command creates symbolic links to the package's skills by default.
+The `skills install` command creates symbolic links to the package's skills by default.
 The boolean `--copy` option copies the skills instead.
 Each installation removes the skill's destination and replaces it with the requested copy or link. The target of any existing symbolic link is preserved.
 
 ```sh
-pnpm exec duplojs-agents-kit install-skill
-pnpm exec duplojs-agents-kit install-skill http-server --type codex
-pnpm exec duplojs-agents-kit install-skill http-client --copy
-pnpm exec duplojs-agents-kit install-skill command --type codex
-pnpm exec duplojs-agents-kit install-skill server --type codex
-pnpm exec duplojs-agents-kit install-skill modeling --type codex
-pnpm exec duplojs-agents-kit install-skill test --type codex
+pnpm exec duplojs-agents-kit skills install
+pnpm exec duplojs-agents-kit skills install http-server --type codex
+pnpm exec duplojs-agents-kit skills install http-client --copy
+pnpm exec duplojs-agents-kit skills install command --type codex
+pnpm exec duplojs-agents-kit skills install server --type codex
+pnpm exec duplojs-agents-kit skills install modeling --type codex
+pnpm exec duplojs-agents-kit skills install test --type codex
+```
+
+Run `skills update` to update DuploJS skills already installed in the selected agent folder. Symbolic links are recreated, including broken links, and copied directories are replaced with a fresh copy, removing obsolete files. Each skill keeps its installation mode. It only updates skills still available in the installed package. Unrelated entries and skills no longer available in the package are preserved; missing skills are not installed.
+
+```sh
+pnpm exec duplojs-agents-kit skills update
+pnpm exec duplojs-agents-kit skills update --type codex
+pnpm exec duplojs-agents-kit skills update --type claude
 ```
 
 Two independently installable skills cover HTTP:
@@ -39,7 +47,7 @@ The `modeling` skill (`duplojs-modeling`) guides business system modeling and im
 
 The `test` skill (`duplojs-test`) guides testing DuploJS results and type contracts, selecting expected Either information, monitoring new result variants with exhaustive selectors, and isolating server dependencies through `TESTImplementation`. It also points to the concepts for organizing E2E tests with `@duplojs/playwright`.
 
-The `command` skill guides the creation of typed CLI commands with `@duplojs/server/command`, including arguments, options, subcommands, help, and executable entry points. Running `install-skill` without a skill installs all supported skills. References and checked TypeScript examples are included in both copied and linked installations.
+The `command` skill guides the creation of typed CLI commands with `@duplojs/server/command`, including arguments, options, subcommands, help, and executable entry points. Running `skills install` without a skill installs all supported skills. References and checked TypeScript examples are included in both copied and linked installations.
 
 The `setup` command creates `AGENTS.md` by default, or `CLAUDE.md` with `--type claude`, in the current project if needed and synchronizes a marked coding conventions block while preserving the surrounding content:
 

package/dist/bin/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { installSkillCommand } from "./installSkill/index.mjs";
+import { skillsCommand } from "./skills/index.mjs";
 import { setupCommand } from "./setup/index.mjs";
 import * as DSCommand from "@duplojs/server/command";
 //#region scripts/bin/index.ts
-await DSCommand.exec({ subjects: [installSkillCommand, setupCommand] }, () => {});
+await DSCommand.exec({ subjects: [skillsCommand, setupCommand] }, () => {});
 //#endregion

package/dist/bin/skills/index.d.ts

@@ -0,0 +1,5 @@
+import * as DSCommand from "@duplojs/server/command";
+export * from './install';
+export * from './update';
+export * from './skill';
+export declare const skillsCommand: DSCommand.Command<"skills">;

package/dist/bin/skills/index.mjs

@@ -0,0 +1,11 @@
+import { AgentTypeEnum, SkillEnum, copySkill, getSkillPaths, getSkillsFolder, symlinkSkill } from "./skill.mjs";
+import { installSkillCommand } from "./install.mjs";
+import { updateSkillsCommand } from "./update.mjs";
+import * as DSCommand from "@duplojs/server/command";
+//#region scripts/bin/skills/index.ts
+const skillsCommand = DSCommand.create("skills", {
+	description: "Install or update DuploJS skills",
+	subjects: [installSkillCommand, updateSkillsCommand]
+}, () => {});
+//#endregion
+export { AgentTypeEnum, SkillEnum, copySkill, getSkillPaths, getSkillsFolder, installSkillCommand, skillsCommand, symlinkSkill, updateSkillsCommand };

package/dist/bin/{installSkill/index.d.ts → skills/install.d.ts}

@@ -1,2 +1,2 @@
 import * as DSCommand from "@duplojs/server/command";
-export declare const installSkillCommand: DSCommand.Command<"install-skill">;
+export declare const installSkillCommand: DSCommand.Command<"install">;

package/dist/bin/{installSkill/index.mjs → skills/install.mjs}

@@ -7,8 +7,8 @@ import * as DPath from "@duplojs/lang/path";
 import * as DSFile from "@duplojs/server/file";
 import * as DEither from "@duplojs/lang/either";
 import * as DArray from "@duplojs/lang/array";
-//#region scripts/bin/installSkill/index.ts
-const installSkillCommand = DSCommand.create("install-skill", {
+//#region scripts/bin/skills/install.ts
+const installSkillCommand = DSCommand.create("install", {
 	options: [DSCommand.createBooleanOption("copy", { description: "Copy skills instead of creating symbolic links" }), DSCommand.createOption("type", DDataStructure.literal(AgentTypeEnum.toTuple()))],
 	subjects: [DSCommand.createArgument("skill", DDataStructure.literal(SkillEnum.toTuple()), { optional: true })]
 }, async ({ args, options }) => {

package/dist/bin/{installSkill → skills}/skill.d.ts

@@ -1,4 +1,5 @@
 import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
 import * as DSFile from "@duplojs/server/file";
 import * as DEither from "@duplojs/lang/either";
 export declare const AgentTypeEnum: {
@@ -23,6 +24,12 @@ export declare const SkillEnum: {
     contract: <GenericContractValue extends string = "fundamental" | "http-server" | "http-client" | "command" | "server" | "modeling" | "test">(...args: (Exclude<"fundamental", GenericContractValue> | Exclude<"http-server", GenericContractValue> | Exclude<"http-client", GenericContractValue> | Exclude<"command", GenericContractValue> | Exclude<"server", GenericContractValue> | Exclude<"modeling", GenericContractValue> | Exclude<"test", GenericContractValue> extends infer InferredMissingValue extends string ? DCommon.IsNever<InferredMissingValue> extends true ? unknown : DCommon.ComputedTypeError<`Enum contract is missing value "${InferredMissingValue}".`> : never) & (Exclude<GenericContractValue, "fundamental" | "http-server" | "http-client" | "command" | "server" | "modeling" | "test"> extends infer InferredUnknownValue extends string ? DCommon.IsNever<InferredUnknownValue> extends true ? unknown : DCommon.ComputedTypeError<`Enum contract contains unknown value "${InferredUnknownValue}".`> : never) extends infer InferredRequirement ? DCommon.IsEqual<InferredRequirement, unknown> extends true ? [] : [] & InferredRequirement : never) => /*elided*/ any;
 };
 type SkillEnum = DCommon.GetEnumValue<typeof SkillEnum>;
+export declare function getSkillsFolder(agentType: AgentTypeEnum): DEither.Error<unknown> | DEither.Success<string & DPath.Path & DPath.Absolute>;
+export declare function getSkillPaths(agentType: AgentTypeEnum, skill: SkillEnum): DEither.Error<unknown> | DEither.Success<{
+    readonly selectedSkillPath: string & DPath.Path & DPath.Absolute;
+    readonly skillsFolder: string & DPath.Path & DPath.Absolute;
+    readonly currentSkillFolder: string & DPath.Path & DPath.Absolute;
+}>;
 export declare function copySkill(agentType: AgentTypeEnum, skill: SkillEnum): Promise<DEither.Error<unknown> | DEither.Left<"file-system-remove-error", DSFile.RemoveErrors> | DEither.Right<"file-system-copy", void> | DEither.Left<"file-system-copy-error", DSFile.CopyErrors>>;
 export declare function symlinkSkill(agentType: AgentTypeEnum, skill: SkillEnum): Promise<DEither.Error<unknown> | DEither.Left<"file-system-remove-error", DSFile.RemoveErrors> | DEither.Left<"file-system-ensure-directory-error", DSFile.EnsureDirectoryErrors> | DEither.Right<"file-system-symlink", void> | DEither.Left<"file-system-symlink-error", DSFile.SymlinkErrors>>;
 export {};

package/dist/bin/{installSkill → skills}/skill.mjs

@@ -5,7 +5,7 @@ import * as DSCommon from "@duplojs/server/common";
 import * as DSFile from "@duplojs/server/file";
 import * as DEither from "@duplojs/lang/either";
 import * as DPattern from "@duplojs/lang/pattern";
-//#region scripts/bin/installSkill/skill.ts
+//#region scripts/bin/skills/skill.ts
 const AgentTypeEnum = DCommon.createEnum([
 	"default",
 	"claude",
@@ -25,18 +25,20 @@ const agentTypeFolderMapper = {
 	codex: ".codex",
 	default: ".agents"
 };
+function getSkillsFolder(agentType) {
+	return DEither.rightPipe(DSCommon.getCurrentWorkDirectory(), (directory) => DPath.resolveRelative([
+		directory,
+		DCommon.cast(agentTypeFolderMapper[agentType]),
+		DCommon.cast("skills")
+	]));
+}
 function getSkillPaths(agentType, skill) {
 	const selectedSkillPath = DPath.resolveRelative([
 		getPackagePath(),
 		DPath.declarePath("skills"),
 		DCommon.cast(skill)
 	]);
-	return DEither.rightPipe(DSCommon.getCurrentWorkDirectory(), (directory) => {
-		const skillsFolder = DPath.resolveRelative([
-			directory,
-			DCommon.cast(agentTypeFolderMapper[agentType]),
-			DCommon.cast("skills")
-		]);
+	return DEither.rightPipe(getSkillsFolder(agentType), (skillsFolder) => {
 		const currentSkillFolder = DPath.resolveRelative([skillsFolder, DCommon.cast(`duplojs-${skill}`)]);
 		return {
 			selectedSkillPath,
@@ -55,4 +57,4 @@ function symlinkSkill(agentType, skill) {
 	return DEither.rightAsyncPipe(getSkillPaths(agentType, skill), ({ selectedSkillPath, skillsFolder, currentSkillFolder }) => DEither.rightAsyncPipe(DSFile.ensureDirectory(skillsFolder), () => removeSkill(currentSkillFolder), () => DSFile.symlink(selectedSkillPath, currentSkillFolder, { type: "dir" })));
 }
 //#endregion
-export { AgentTypeEnum, SkillEnum, copySkill, symlinkSkill };
+export { AgentTypeEnum, SkillEnum, copySkill, getSkillPaths, getSkillsFolder, symlinkSkill };

package/dist/bin/skills/update.d.ts

@@ -0,0 +1,2 @@
+import * as DSCommand from "@duplojs/server/command";
+export declare const updateSkillsCommand: DSCommand.Command<"update">;

package/dist/bin/skills/update.mjs

@@ -0,0 +1,19 @@
+import { AgentTypeEnum, SkillEnum, copySkill, getSkillPaths, symlinkSkill } from "./skill.mjs";
+import * as DSCommand from "@duplojs/server/command";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+//#region scripts/bin/skills/update.ts
+const updateSkillsCommand = DSCommand.create("update", {
+	description: "Update installed DuploJS skills, preserving copies and symbolic links",
+	options: [DSCommand.createOption("type", DDataStructure.literal(AgentTypeEnum.toTuple()))]
+}, async ({ options }) => {
+	const agentType = options.type ?? "default";
+	for (const skill of SkillEnum.toTuple()) await DEither.rightAsyncPipe(getSkillPaths(agentType, skill), ({ currentSkillFolder }) => DSFile.linkStat(currentSkillFolder), (stat) => {
+		if (stat.isSymlink) return symlinkSkill(agentType, skill);
+		if (stat.isDirectory) return copySkill(agentType, skill);
+		return DEither.ok();
+	});
+});
+//#endregion
+export { updateSkillsCommand };

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">;