Getting Started

Installation

@duplojs/server-utils is used with @duplojs/utils, which provides Either and 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

The library is designed to unify usage across modern server runtimes: Node, Bun, and Deno. With the same API, you keep the same application behavior even when the runtime changes.

File

The file namespace covers filesystem operations without locking you into one runtime-specific API.

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);
}

Use it to read or write files, manipulate JSON, create temporary folders, walk a directory tree, or move resources.

The fileInterface, folderInterface, and unknownInterface helpers represent a resource as something richer than its path. You start from a path, identify it as a file, folder, or unknown resource, then manipulate that representation through consistent methods. This is useful when a resource should move through your code as a domain object instead of a plain string.

Common

The common namespace groups runtime helpers. For applications, the most important one is often environmentVariable: it loads variables from the process and env files, expands references, then validates the result with 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);
}

This replaces blind .env loading with a real validation boundary. Invalid variables are caught at startup, types are known in code, and env files remain optional depending on your strategy.

Command

The command namespace builds typed CLIs. You declare options, positional arguments, and subcommands; the library reads process arguments, generates help, and turns parsing errors into readable messages.

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);
	},
);

For a script that only needs options, execOptions is the lightweight version: typed parsing and automatic help without building a full command.

API

Guides give context and a reading path. For complete signatures, use the reference namespaces:

• Common for runtime helpers and environment variables;
• File for filesystem work;
• Command for CLIs;
• DataParser for server parsers.