Bien démarrer

Installation

@duplojs/server-utils s'utilise avec @duplojs/utils, qui fournit notamment Either et les DataParser.

npm

npm install @duplojs/server-utils@0 @duplojs/utils@1

yarn

yarn add @duplojs/server-utils@0 @duplojs/utils@1

pnpm

pnpm add @duplojs/server-utils@0 @duplojs/utils@1

bun

bun add @duplojs/server-utils@0 @duplojs/utils@1

deno

deno add npm:@duplojs/server-utils@0 npm:@duplojs/utils@1

La librairie est pensée pour uniformiser les usages entre les runtimes modernes côté serveur: Node, Bun et Deno. Avec la même API, vous gardez le même comportement applicatif même si le runtime change.

File

Le namespace file couvre les opérations de fichiers sans vous enfermer dans une API spécifique à un runtime.

import { SF } from "@duplojs/server-utils";
import { E, unwrap } from "@duplojs/utils";

const result = await SF.readTextFile("./config.json");

if (E.isRight(result)) {
	const content = unwrap(result);
	console.log(content);
}

Vous l'utilisez pour lire ou écrire des fichiers, manipuler du JSON, créer des dossiers temporaires, parcourir une arborescence ou déplacer des ressources.

Les interfaces fileInterface, folderInterface et unknownInterface servent à représenter une ressource autrement que par son path. Vous partez d'un chemin, vous l'identifiez comme fichier, dossier ou ressource inconnue, puis vous manipulez cette représentation avec des méthodes cohérentes. C'est utile quand une ressource doit circuler dans votre code comme un objet métier plutôt que comme une simple chaîne.

Common

Le namespace common regroupe les helpers liés au runtime. Le plus important pour une application est souvent environmentVariable: il charge les variables du process et des fichiers env, développe les références, puis valide le résultat avec des DataParser.

import { environmentVariable } from "@duplojs/server-utils";
import { DP, E, unwrap } from "@duplojs/utils";

const result = await environmentVariable(
	{
		NODE_ENV: DP.literal(["development", "production", "test"]),
		PORT: DP.coerce.number(),
		DATABASE_URL: DP.string(),
	},
	{
		paths: [".env", ".env.local"],
	},
);

if (E.isRight(result)) {
	const env = unwrap(result);
	console.log(env.PORT);
}

Cette approche remplace le chargement aveugle d'un fichier .env par une vraie frontière de validation. Les variables invalides sont détectées au démarrage, les types sont connus dans le code, et les fichiers env restent optionnels selon votre stratégie.

Command

Le namespace command sert à construire des CLI typées. Vous déclarez des options, des arguments positionnels et des sous-commandes; la librairie se charge de lire les arguments du process, de générer le help et de transformer les erreurs de parsing en messages lisibles.

import { SC } from "@duplojs/server-utils";
import { DP } from "@duplojs/utils";

await SC.exec(
	{
		description: "Greet someone",
		options: [SC.createBooleanOption("shout", { aliases: ["s"] })],
		subjects: [SC.createArgument("name", DP.string())],
	},
	({ options, args: { name } }) => {
		const message = `hello ${name}`;

		console.log(options.shout ? message.toUpperCase() : message);
	},
);

Pour un script qui n'a besoin que d'options, execOptions est la version légère: vous gardez le parsing typé et le help automatique sans construire une commande complète.

API

Les guides donnent le contexte et le chemin de lecture. Pour les signatures complètes, consultez ensuite les namespaces de référence:

• Common pour le runtime et les variables d'environnement;
• File pour le système de fichiers;
• Command pour les CLI;
• DataParser pour les parsers serveur.