@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.6

package/docs/concepts/01-fundamental/05-chrono/20-manipulation.ts

@@ -0,0 +1,110 @@
+/**
+ * @title Calculs et comparaisons temporels.
+ *
+ * Transformer, comparer et décomposer des instants ou durées avec les fonctions Chrono.
+ */
+import * as DChrono from "@duplojs/lang/chrono";
+import * as DCommon from "@duplojs/lang/common";
+
+// TheDate et TheTime sont immuables : les transformations produisent de nouvelles valeurs.
+// Les formes curifiées permettent de composer ces transformations dans un pipe.
+const date = DChrono.createDate("2026-09-30");
+
+// Les unités peuvent être ajoutées ou retirées directement sur une date.
+
+const nextWeek = DCommon.pipe(
+	date,
+	DChrono.addWeeks(1),
+	DChrono.addDays(2),
+	DChrono.subtractHours(3),
+);
+type _CheckNextWeekLine16 = DCommon.ExpectType<
+	typeof nextWeek,
+	DChrono.TheDate,
+	"strict"
+>;
+
+// `TheTime` permet de représenter une durée puis de l'appliquer
+// à une date ou à un autre temps.
+const duration = DChrono.createTime(2, "hour");
+
+const later = DCommon.pipe(
+	date,
+	DChrono.addTime(duration),
+);
+type _CheckLaterLine28 = DCommon.ExpectType<
+	typeof later,
+	DChrono.TheDate,
+	"strict"
+>;
+
+const totalDuration = DCommon.pipe(
+	duration,
+	DChrono.addTime(DChrono.createTime(30, "minute")),
+);
+type _CheckTotalDurationLine34 = DCommon.ExpectType<
+	typeof totalDuration,
+	DChrono.TheTime,
+	"strict"
+>;
+
+// La différence entre deux dates produit un TheTime signé : date moins date de référence.
+const startDate = DChrono.createDate("2026-09-01");
+const endDate = DChrono.createDate("2026-09-30");
+
+const difference = DCommon.pipe(
+	endDate,
+	DChrono.getDifference(startDate),
+);
+type _CheckDifferenceLine44 = DCommon.ExpectType<
+	typeof difference,
+	DChrono.TheTime,
+	"strict"
+>;
+
+// `computeTime` permet d'exprimer un `TheTime` dans une unité donnée.
+
+// 696
+const differenceInHours = DCommon.pipe(
+	difference,
+	DChrono.computeTime("hour"),
+);
+
+// round ramène une date au début d’une unité du calendrier UTC.
+
+// DChrono.TheDate -> 2026-09-30T00:00:00.000Z
+const startOfDay = DChrono.round(date, "day");
+
+// DChrono.TheDate -> 2026-09-01T00:00:00.000Z
+const startOfMonth = DChrono.round(date, "month");
+
+// Des helpers permettent de récupérer différentes parties d'une date.
+
+const year = DChrono.getYear(date);
+const month = DChrono.getMonth(date);
+const day = DChrono.getDayOfMonth(date);
+const week = DChrono.getWeekOfYear(date);
+
+const firstDayOfMonth = DChrono.getFirstDayOfMonth(date);
+const lastDayOfMonth = DChrono.getLastDayOfMonth(date);
+
+// Les dates et les temps possèdent leurs propres opérateurs de comparaison.
+
+const limitDate = DChrono.createDate("2026-10-01");
+
+const isBeforeLimit = DChrono.lessThanDate(
+	date,
+	limitDate,
+);
+
+const isAfterLimit = DCommon.pipe(
+	date,
+	DChrono.greaterThanDate(startDate),
+);
+
+const maxDuration = DChrono.createTime(3, "hour");
+
+const isDurationAllowed = DCommon.pipe(
+	duration,
+	DChrono.lessThanOrEqualTime(maxDuration),
+);

package/docs/concepts/01-fundamental/05-chrono/30-serialized.ts

@@ -0,0 +1,89 @@
+/**
+ * @title Transport et reconstruction des valeurs temporelles.
+ *
+ * Sérialiser, reconnaître et reconstruire les instants et durées en conservant leur valeur.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DChrono from "@duplojs/lang/chrono";
+
+// Chrono possède un format dédié qui conserve la valeur numérique et identifie sa nature.
+// Il sert au transport des données : JSON, API, persistance ou messages.
+const date = DChrono.createDate("2026-09-30");
+const time = DChrono.createTime(2, "hour");
+
+// Une `TheDate` est sérialisée avec le préfixe `date`,
+// suivi de son timestamp et de son signe.
+
+const serializedDate = DChrono.serialize(date);
+type _CheckSerializedDateLine18 = DCommon.ExpectType<
+	typeof serializedDate,
+	`date${number}-` | `date${number}+`,
+	"strict"
+>;
+
+// Un `TheTime` utilise le même principe avec le préfixe `time`.
+
+const serializedTime = DChrono.serialize(time);
+type _CheckSerializedTimeLine24 = DCommon.ExpectType<
+	typeof serializedTime,
+	`time${number}-` | `time${number}+`,
+	"strict"
+>;
+
+// Le format permet de conserver exactement la valeur transportée,
+// tout en distinguant une date d'un simple nombre ou d'une string classique.
+
+// Les instances se sérialisent également automatiquement avec JSON,
+// grâce à leur méthode `toJSON`.
+
+const payload = JSON.stringify({
+	date,
+	time,
+});
+type _CheckPayload = DCommon.ExpectType<typeof payload, string, "strict">;
+
+// {
+//     "date": "date1790726400000+",
+//     "time": "time7200000+"
+// }
+
+// Une string reçue depuis l'extérieur peut être reconnue
+// avant d'être utilisée comme valeur sérialisée.
+
+declare const input: string;
+
+if (DChrono.isSerializedTheDate(input)) {
+	const serializedDate = input;
+	type _CheckSerializedDateLine49 = DCommon.ExpectType<
+	typeof serializedDate,
+	`date${number}-` | `date${number}+`,
+	"strict"
+	>;
+}
+
+if (DChrono.isSerializedTheTime(input)) {
+	const serializedTime = input;
+	type _CheckSerializedTimeLine54 = DCommon.ExpectType<
+	typeof serializedTime,
+	`time${number}-` | `time${number}+`,
+	"strict"
+	>;
+}
+
+// Une valeur sérialisée peut ensuite être reconstruite.
+
+const restoredDate = DChrono.createDateOrThrow(serializedDate);
+const restoredTime = DChrono.createTimeOrThrow(serializedTime);
+
+// Les fonctions de manipulation de `chrono` acceptent également
+// directement les formats sérialisés dans de nombreux cas.
+
+const nextDay = DChrono.addDays(
+	serializedDate,
+	1,
+);
+
+const durationInHours = DChrono.computeTime(
+	serializedTime,
+	"hour",
+);

package/docs/concepts/01-fundamental/05-chrono/40-timezone.ts

@@ -0,0 +1,85 @@
+/**
+ * @title Interprétation et affichage dans un fuseau horaire.
+ *
+ * Interpréter une heure locale et lire ou présenter un instant dans le fuseau demandé.
+ */
+import * as DChrono from "@duplojs/lang/chrono";
+import * as DCommon from "@duplojs/lang/common";
+
+// TheDate stocke un instant absolu sous forme de timestamp, sans fuseau attaché.
+// Le fuseau intervient pour interpréter une heure locale ou lire un instant dans un contexte local.
+// Les fuseaux acceptés sont typés avec DChrono.Timezone.
+
+// Une date littérale YYYY-MM-DD est interprétée en UTC.
+const utcDate = DChrono.createDate("2026-09-30");
+
+// Une date provenant d'une valeur locale peut préciser son fuseau.
+//
+// Ici, "2026-09-30T09:00:00" représente 09:00 à Paris.
+// Le `TheDate` obtenu conserve l'instant correspondant sous forme de timestamp.
+const parisDate = DChrono.createDateOrThrow({
+	value: "2026-09-30T09:00:00",
+	timezone: "Europe/Paris",
+});
+
+// `applyTimezone` permet la même conversion lorsqu'une `TheDate` existe déjà.
+//
+// Cette opération change le timestamp : elle interprète les composantes UTC de l’entrée
+// comme une heure locale
+// dans le fuseau demandé, puis convertie vers l'instant correspondant.
+const localDate = DChrono.createDate("2026-09-30", {
+	hour: "09",
+});
+
+const instant = DCommon.pipe(
+	localDate,
+	DChrono.applyTimezone("Europe/Paris"),
+);
+type _CheckInstantLine35 = DCommon.ExpectType<
+	typeof instant,
+	DChrono.TheDate,
+	"strict"
+>;
+
+// `getTimezoneOffset` retourne le décalage du fuseau pour une date donnée.
+// Ce décalage dépend notamment des changements d'heure saisonniers.
+
+// number, en millisecondes
+const parisOffset = DChrono.getTimezoneOffset(
+	instant,
+	"Europe/Paris",
+);
+
+// Pour lire une date dans un fuseau, il ne faut pas modifier son timestamp.
+// Les getters acceptent directement un timezone.
+
+const year = DChrono.getYear(
+	instant,
+	"Europe/Paris",
+);
+
+const month = DChrono.getMonth(
+	instant,
+	"Europe/Paris",
+);
+
+const day = DChrono.getDayOfMonth(
+	instant,
+	"Europe/Paris",
+);
+
+const hour = DChrono.getHour(
+	instant,
+	"Europe/Paris",
+);
+
+// `formatDate` suit le même principe :
+// l'instant reste identique, seule sa représentation dépend du fuseau.
+
+const formattedDate = DCommon.pipe(
+	instant,
+	DChrono.formatDate(
+		"YYYY-MM-DD HH:mm:ss ZZ",
+		"Europe/Paris",
+	),
+);

package/docs/concepts/01-fundamental/05-chrono/index.md

@@ -0,0 +1,3 @@
+## Chrono
+
+Représentation des instants et durées : création, calculs, comparaison, sérialisation et fuseaux horaires.

package/docs/concepts/01-fundamental/06-modeling/10-new-type.ts

@@ -0,0 +1,42 @@
+/**
+ * @title Identité et contraintes des types métier.
+ *
+ * Distinguer des valeurs de même représentation par des NewType propres à leur rôle métier.
+ */
+import * as DModeling from "@duplojs/lang/modeling";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+
+// Un NewType associe une identité de typage à une structure et à des contraintes métier.
+// Cette identité ne modifie pas la représentation runtime de la valeur.
+const SenderEmail = DModeling.createNewType(
+	"SenderEmail",
+	DDataStructure.string(),
+	[DDataStructure.email()],
+);
+type SenderEmail = DDataStructure.StructureValue<typeof SenderEmail>;
+
+const RecipientEmail = DModeling.createNewType(
+	"RecipientEmail",
+	DDataStructure.string(),
+	[DDataStructure.email()],
+);
+type RecipientEmail = DDataStructure.StructureValue<typeof RecipientEmail>;
+
+// map vérifie la structure et les contraintes avant de produire le type métier.
+// Un échec reste représenté par un Either ; OrThrow est utilisé ici pour des constantes connues.
+const sender = DEither.unwrapRightOrThrow(SenderEmail.map("alice@example.com"));
+const recipient = DEither.unwrapRightOrThrow(RecipientEmail.map("bob@example.com"));
+
+declare function sendMessage(sender: SenderEmail): void;
+
+sendMessage(sender);
+
+// @ts-expect-error Une adresse destinataire ne possède pas l’identité SenderEmail.
+sendMessage(recipient);
+
+// @ts-expect-error Une string seule ne possède pas l’identité métier attendue.
+sendMessage("alice@example.com");
+
+// Les deux types reposent sur la même représentation, mais leurs rôles ne sont pas interchangeables.
+// Le namespace d’une Entity peut aussi créer des NewType préfixés par le nom de cette entité.

package/docs/concepts/01-fundamental/06-modeling/20-entity.ts

@@ -0,0 +1,191 @@
+/**
+ * @title Entités métier et hydratation.
+ *
+ * Déclarer les propriétés métier, hydrater les données externes et mettre à jour les valeurs typées.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DModeling from "@duplojs/lang/modeling";
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+import type * as DNumber from "@duplojs/lang/number";
+
+// Une Entity représente un objet métier doté d’une identité explicite.
+// Ses valeurs primitives sont définies par des NewType qui associent un sens métier
+// et des contraintes à leur représentation. Des collections, objets imbriqués,
+// autres Entity ou TaggedObject peuvent également composer la shape.
+export namespace User {
+	// Un namespace d'entité permet de regrouper la définition de l'entité
+	// et de ses `NewType`.
+	//
+	// Les noms des `NewType` créés avec ce namespace sont automatiquement
+	// préfixés par le nom de l'entité.
+	const namespace = DModeling.createEntityNamespace("User");
+
+	export const Id = namespace.createNewType(
+		"Id",
+		DDataStructure.string(),
+		[DDataStructure.uuid()],
+	);
+	export type Id = DDataStructure.StructureValue<typeof Id>;
+	type _CheckId = DCommon.ExpectType<Id, string & DModeling.NewType<"UserId", DString.Uuid>, "strict">;
+
+	export const Age = namespace.createNewType(
+		"Age",
+		DDataStructure.number(),
+		[
+			DDataStructure.integer(),
+			DDataStructure.positive(),
+		],
+	);
+	export type Age = DDataStructure.StructureValue<typeof Age>;
+	type _CheckAge = DCommon.ExpectType<
+		Age,
+		number & DModeling.NewType<"UserAge", DNumber.Integer | DNumber.Positive>,
+		"strict"
+	>;
+
+	export const Name = namespace.createNewType(
+		"Name",
+		DDataStructure.string(),
+		[
+			DDataStructure.trimmed(),
+			DDataStructure.minCharacters(3),
+			DDataStructure.maxCharacters(45),
+		],
+	);
+	export type Name = DDataStructure.StructureValue<typeof Name>;
+	type _CheckName = DCommon.ExpectType<
+		Name,
+		string & DModeling.NewType<"UserName", DString.Trimmed | DString.MinCharacters<3> | DString.MaxCharacters<45>>,
+		"strict"
+	>;
+
+	export const Tag = namespace.createNewType(
+		"Tag",
+		DDataStructure.string(),
+		[
+			DDataStructure.trimmed(),
+			DDataStructure.minCharacters(2),
+			DDataStructure.maxCharacters(20),
+		],
+	);
+	export type Tag = DDataStructure.StructureValue<typeof Tag>;
+	type _CheckTag = DCommon.ExpectType<Tag, string & DModeling.NewType<"UserTag", DString.Trimmed | DString.MinCharacters<2> | DString.MaxCharacters<20>>, "strict">;
+
+	// L'entité est ensuite déclarée à partir de ses différentes propriétés.
+	//
+	export const Entity = namespace.createEntity(
+		() => ({
+			id: Id,
+			age: Age,
+			name: Name,
+			tags: DDataStructure.array(Tag),
+		}),
+	);
+	export type Entity = DDataStructure.StructureValue<typeof Entity>;
+	type _CheckEntity = DCommon.ExpectType<Entity, DModeling.Entity<"User"> & {
+		readonly id: Id;
+		readonly age: Age;
+		readonly name: Name;
+		readonly tags: readonly Tag[];
+	}, "strict">;
+}
+
+// L’hydratation fait entrer dans le modèle métier des données de repository ou de base de données.
+// Une donnée provenant d’un système externe possède généralement un typage
+// amoindri par rapport au modèle métier.
+//
+// Les contraintes et les `NewType` ne sont plus présents, mais les types
+// primitifs restent connus.
+//
+// `map` permet d'hydrater l'entité depuis cette représentation.
+//
+// Les contraintes sont vérifiées pendant cette opération.
+// Le mapping pouvant échouer, son résultat est représenté par un `Either`.
+
+const maybeMapUser = User.Entity.map({
+	id: "invalid-id",
+	name: "SuperName",
+	age: 12,
+	tags: ["superTag"],
+});
+type _CheckMaybeMapUser = DCommon.ExpectType<typeof maybeMapUser, DEither.Left<"async-error", DDataStructure.ErrorPromise> | DEither.Left<"map-error", DDataStructure.Error> | DEither.Right<"map-success", User.Entity>, "strict">;
+
+// `decodeMap` applique le même principe à une donnée encodée.
+//
+// La représentation demandée en entrée dépend des codecs utilisés.
+// Avec `codecsString`, les types fondamentaux qui possèdent une représentation
+// string sont attendus sous cette forme.
+//
+// L'âge de l'entité est donc ici fourni dans sa représentation encodée
+// plutôt que directement comme un `number`.
+
+const maybeDecodeMapUser = User.Entity.decodeMap(DDataStructure.codecsString, {
+	id: "550e8400-e29b-41d4-a716-446655440000",
+	name: "SuperName",
+	age: DCommon.cast("12"),
+	tags: ["superTag"],
+});
+type _CheckMaybeDecodeMapUser = DCommon.ExpectType<typeof maybeDecodeMapUser, DEither.Left<"async-error", DDataStructure.ErrorPromise> | DEither.Left<"map-error", DDataStructure.Error> | DEither.Right<"map-success", User.Entity>, "strict">;
+
+// `new` est utilisé lorsque les propriétés possèdent déjà leur typage métier.
+//
+// Ici, chaque `NewType` est d'abord hydraté individuellement avec `map`.
+// `DEither.group` regroupe ensuite les différentes opérations avant de fournir
+// leurs valeurs à `User.Entity.new`.
+//
+// `new` n'effectue donc pas lui-même le mapping des propriétés.
+// Il construit l'entité à partir de valeurs déjà correctement typées.
+//
+// Le résultat du `rightPipe` conserve la monade `Success` produite après
+// regroupement des différentes validations.
+
+const maybeUser = DEither.rightPipe(
+	DEither.group({
+		id: User.Id.map("550e8400-e29b-41d4-a716-446655440000"),
+		name: User.Name.map("SuperName"),
+		age: User.Age.map(24),
+		tags: DEither.rightPipe(
+			User.Tag.map("superTag"),
+			DArray.coalescing,
+		),
+	}),
+	User.Entity.new,
+);
+type _CheckMaybeUser = DCommon.ExpectType<typeof maybeUser, DEither.Left<"async-error", DDataStructure.ErrorPromise> | DEither.Left<"map-error", DDataStructure.Error> | DEither.Success<DModeling.Entity<"User"> & {
+	readonly id: User.Id;
+	readonly name: User.Name;
+	readonly age: User.Age;
+	readonly tags: readonly [User.Tag];
+}>, "strict">;
+
+declare const user: User.Entity;
+declare const maybeAge: User.Age | undefined;
+
+const updatedUser = User.Entity.update(
+	user,
+	{
+		age: maybeAge,
+	},
+);
+type _CheckUpdatedUser = DCommon.ExpectType<typeof updatedUser, User.Entity, "strict">;
+
+// `update` retourne une nouvelle entité en remplaçant uniquement
+// les propriétés dont la nouvelle valeur n'est pas `undefined`.
+//
+// Contrairement à un spread classique, une valeur `undefined`
+// n'écrase donc pas la valeur déjà présente sur l'entité.
+//
+// Si `maybeAge` vaut `undefined`, `user.age` est conservé.
+// Sinon, sa valeur remplace l'âge existant.
+//
+// Les nouvelles valeurs ne sont pas validées par `update` :
+// elles doivent déjà posséder le typage métier attendu.
+
+// `map` et `decodeMap` existent aussi sur les `NewType`.
+// Ces opérations ne sont donc pas spécifiques aux entités.
+//
+// Les variantes `asyncMap` et `asyncDecodeMap` permettent la même hydratation
+// lorsque la structure contient des traitements asynchrones.