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

package/docs/concepts/01-fundamental/04-data-structure/60-interpret-error.ts

@@ -0,0 +1,123 @@
+/**
+ * @title Interprétation des erreurs de validation et de conversion.
+ *
+ * Localiser les données invalides et adapter les messages au contexte ou à la langue.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+
+// Les erreurs conservent leur source : structure, type, contrainte ou codec.
+// Les dictionnaires séparent cette information technique de sa représentation finale
+// pour une interface utilisateur, une API, des logs ou une traduction.
+const userStructure = DDataStructure.object({
+	email: DDataStructure.string([DDataStructure.email()]),
+	age: DDataStructure.number([DDataStructure.greaterThanOrEqual(18)]),
+});
+
+const checkResult = userStructure.check({
+	email: "invalid-email",
+	age: 12,
+});
+
+// Une erreur contient une liste de `issues`.
+// Chaque issue conserve notamment :
+// - la donnée invalide,
+// - son chemin,
+// - la structure source,
+// - et éventuellement le `Type` ou la `Constraint` responsable.
+const error = DCommon.pipe(
+	checkResult,
+	DEither.unwrapByInformationOrThrow("check-error"),
+);
+
+// Un interpréteur peut utiliser les dictionnaires fournis par DuploJS.
+const interpretError = DDataStructure.createErrorInterpreter(
+	DDataStructure.defaultErrorInterpreterDataStructureDictionary,
+	DDataStructure.defaultErrorInterpreterCodecDictionary,
+);
+
+const interpretedIssues = interpretError(error);
+
+// Exemple d'une issue liée à `email()` :
+//
+// {
+//     path: "email",
+//     data: "invalid-email",
+//     interpretedMessage: {
+//         interpretedSource: "Expected a value matching the configured type.",
+//         interpretedSubSource: "Expected a valid email address.",
+//     },
+// }
+//
+// `interpretedSource` correspond à la structure principale de l'issue.
+// `interpretedSubSource` correspond au `Type` ou à la `Constraint`
+// ayant provoqué l'erreur.
+
+// Les dictionnaires peuvent être étendus ou surchargés.
+// Le callback reçoit directement la source avec son type précis.
+const customDataStructureDictionary = {
+	...DDataStructure.defaultErrorInterpreterDataStructureDictionary,
+
+	"@DuplojsLangDataStructure/email-constraint": () => (
+		"L'adresse email est invalide."
+	),
+
+	"@DuplojsLangDataStructure/greater-than-or-equal-constraint": (
+		constraint,
+	) => (
+		`La valeur doit être supérieure ou égale à ${constraint.definition.threshold}.`
+	),
+} satisfies DDataStructure.StructureDictionaryParams;
+
+const customInterpretError = DDataStructure.createErrorInterpreter(
+	customDataStructureDictionary,
+	DDataStructure.defaultErrorInterpreterCodecDictionary,
+);
+
+const customInterpretedIssues = customInterpretError(error);
+
+// Les messages peuvent également être définis directement sur une instance
+// de structure, de type ou de contrainte avec `addMessage`.
+//
+// Le dictionnaire représente une interprétation globale d'un type d'erreur.
+// `addMessage` représente un message spécifique à une instance.
+
+const emailConstraint = DDataStructure.email()
+	.addMessage("L'email du compte doit être valide.");
+
+const accountStructure = DDataStructure.object({
+	email: DDataStructure.string([emailConstraint]),
+});
+
+// Dans ce cas, l'issue conservera les deux informations :
+//
+// interpretedMessage: {
+//     subSource: "L'email du compte doit être valide.",
+//     interpretedSubSource: "Expected a valid email address.",
+// }
+//
+// `subSource` vient du message défini directement sur la contrainte.
+// `interpretedSubSource` vient du dictionnaire.
+
+// Les erreurs de codecs suivent le même principe.
+//
+// Contrairement aux structures, les codecs sont identifiés directement
+// par leur instance dans le dictionnaire.
+const codecInterpreter = DDataStructure.createErrorInterpreter(
+	DDataStructure.defaultErrorInterpreterDataStructureDictionary,
+	DDataStructure.defaultErrorInterpreterCodecDictionary,
+);
+
+// L'interpréteur permet donc de séparer :
+//
+// DataStructure
+//      |
+//      v
+// Error + Issues
+//      |
+//      v
+// createErrorInterpreter
+//      |
+//      v
+// messages adaptés au contexte d'utilisation.

package/docs/concepts/01-fundamental/04-data-structure/index.md

@@ -0,0 +1,3 @@
+## DataStructure
+
+Contrats de données partagés entre TypeScript et runtime : composition, validation, contraintes, représentations, récursivité et erreurs.

package/docs/concepts/01-fundamental/05-chrono/01-use.ts

@@ -0,0 +1,14 @@
+/**
+ * @title Représentation des instants et des durées.
+ *
+ * TheDate et TheTime pour modéliser le temps avec des valeurs immuables.
+ */
+import * as DChrono from "@duplojs/lang/chrono";
+
+// TheDate représente un instant absolu ; TheTime une durée ou une quantité de temps.
+// Privilégier ces types aux Date et number natifs dans le domaine pour rendre ce sens explicite.
+const instant = DChrono.createDate("2026-09-30");
+const duration = DChrono.createTime(2, "hour");
+
+// La transformation produit un nouvel instant ; la valeur initiale reste inchangée.
+const later = DChrono.addTime(instant, duration);

package/docs/concepts/01-fundamental/05-chrono/10-creation.ts

@@ -0,0 +1,59 @@
+/**
+ * @title Création des instants et des durées.
+ *
+ * Valeurs connues statiquement ou reçues au runtime, et gestion des entrées invalides.
+ */
+import * as DChrono from "@duplojs/lang/chrono";
+
+// TheDate représente un instant absolu ; TheTime représente une quantité de temps.
+// Lorsque le typage peut établir la validité de l’entrée, la création retourne directement
+// TheDate ou TheTime. Sinon, un Either exprime la réussite ou l’échec de la création.
+
+// Les dates littérales au format YYYY-MM-DD sont vérifiées par le typage.
+
+// DChrono.TheDate
+const date = DChrono.createDate("2026-09-30");
+
+// Les temps sont également sûrs lorsque la valeur littérale
+// et son unité permettent d'être vérifiées par le typage.
+
+// DChrono.TheTime
+const time = DChrono.createTime(2, "hour");
+
+// Lorsque la valeur provient du runtime, sa validité n'est plus garantie.
+declare const dateInput: string;
+declare const timeInput: number;
+
+// DChrono.MayBeDate
+// DEither.Right<"date-created", DChrono.TheDate>
+// | DEither.Left<"date-created-error", null>
+const maybeDate = DChrono.createDate({
+	value: dateInput,
+});
+
+// DChrono.MayBeTime
+// DEither.Right<"time-created", DChrono.TheTime>
+// | DEither.Left<"time-created-error", null>
+// Sans unité explicite, l’entrée numérique représente des millisecondes.
+const maybeTime = DChrono.createTime(timeInput);
+
+// Les variantes `OrThrow` permettent de récupérer directement la valeur.
+// Une entrée invalide provoquera une `CreateTheDateError`
+// ou une `CreateTheTimeError`.
+
+// DChrono.TheDate
+const dateOrThrow = DChrono.createDateOrThrow({
+	value: dateInput,
+});
+
+// DChrono.TheTime
+const timeOrThrow = DChrono.createTimeOrThrow(timeInput);
+
+// Les objets natifs et timestamps sont également considérés
+// comme des valeurs runtime potentiellement invalides.
+
+// DChrono.MayBeDate
+const maybeNativeDate = DChrono.createDate(new Date());
+
+// DChrono.MayBeDate
+const maybeTimestampDate = DChrono.createDate(Date.now());

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

@@ -0,0 +1,94 @@
+/**
+ * @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.
+
+// DChrono.TheDate
+const nextWeek = DCommon.pipe(
+	date,
+	DChrono.addWeeks(1),
+	DChrono.addDays(2),
+	DChrono.subtractHours(3),
+);
+
+// `TheTime` permet de représenter une durée puis de l'appliquer
+// à une date ou à un autre temps.
+const duration = DChrono.createTime(2, "hour");
+
+// DChrono.TheDate
+const later = DCommon.pipe(
+	date,
+	DChrono.addTime(duration),
+);
+
+// DChrono.TheTime
+const totalDuration = DCommon.pipe(
+	duration,
+	DChrono.addTime(DChrono.createTime(30, "minute")),
+);
+
+// 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");
+
+// DChrono.TheTime
+const difference = DCommon.pipe(
+	endDate,
+	DChrono.getDifference(startDate),
+);
+
+// `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,73 @@
+/**
+ * @title Transport et reconstruction des valeurs temporelles.
+ *
+ * Sérialiser, reconnaître et reconstruire les instants et durées en conservant leur valeur.
+ */
+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.
+
+// DChrono.SerializedTheDate
+// "date1790726400000+"
+const serializedDate = DChrono.serialize(date);
+
+// Un `TheTime` utilise le même principe avec le préfixe `time`.
+
+// DChrono.SerializedTheTime
+// "time7200000+"
+const serializedTime = DChrono.serialize(time);
+
+// 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,
+});
+
+// {
+//     "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)) {
+	// DChrono.SerializedTheDate
+	const serializedDate = input;
+}
+
+if (DChrono.isSerializedTheTime(input)) {
+	// DChrono.SerializedTheTime
+	const serializedTime = input;
+}
+
+// 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,81 @@
+/**
+ * @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",
+});
+
+// DChrono.TheDate
+const instant = DCommon.pipe(
+	localDate,
+	DChrono.applyTimezone("Europe/Paris"),
+);
+
+// `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é.