lavender-std

Simple, typed stdin prompts with reusable validation helpers for Node.js CLIs.

lavender-std gives you a tiny standard input layer for asking questions, validating answers, applying defaults, and closing the readline session when your CLI is done.

Made by lavender-incognito.

Features

• Promise-based ask() helper for clean async CLI flows.
• Built-in validators for required values, length limits, numbers, ranges, email, regex, and allowed choices.
• Custom validator support for project-specific rules.
• Default values for prompts.
• TypeScript declarations included.
• Small ESM package with no runtime dependencies.

Install

npm install lavender-std

Quick Start

import { ask, done, valid } from "lavender-std";

async function main() {
  const username = await ask(
    "Username:",
    [
      valid.required("Username is required"),
      valid.minLength(3, "Username must be at least 3 characters"),
      valid.regex(
        /^[a-zA-Z0-9_]+$/,
        "Username can only contain letters, numbers, and underscores",
      ),
    ],
    "john_doe",
  );

  const age = await ask(
    "Age:",
    [
      valid.required("Age is required"),
      valid.number("Age must be a whole number"),
      valid.min(18, "You must be at least 18 years old"),
    ],
    18,
  );

  console.log(`Welcome, ${username}. Age: ${age}`);

  done();
}

main();

API

ask(question, rules?, defaultValue?)

Asks a question in the terminal and returns the validated answer as a promise.

function ask(
  question: string,
  rules?: Validator[],
  defaultValue?: string | number | boolean,
): Promise<string>;

Parameters:

• question: The text shown to the user.
• rules: Optional array of validators. Validators run in order.
• defaultValue: Optional value used when the user submits an empty answer.

If validation fails, ask() prints the validation error and asks the same question again.

done()

Closes the internal readline interface.

Call this when your CLI has finished asking questions:

done();

valid

Collection of validator factories.

Each validator returns null when the value is valid, or a string error message when invalid.

type Validator = (val: string) => string | null;

Validators

valid.required(msg?)

Requires a non-empty value.

valid.required("This field is required");

valid.minLength(n, msg?)

Requires at least n characters.

valid.minLength(3, "Must be at least ");

valid.maxLength(n, msg?)

Requires no more than n characters.

valid.maxLength(20, "Must be no more than ");

valid.number(msg?)

Requires a whole number.

valid.number("Input must be a whole number");

valid.min(n, msg?)

Requires a number greater than or equal to n.

valid.min(18, "Minimum value is ");

valid.max(n, msg?)

Requires a number less than or equal to n.

valid.max(120, "Maximum value is ");

valid.email(msg?)

Requires an email-like value.

valid.email("Invalid email address");

valid.regex(pattern, msg?)

Requires the value to match a regular expression.

valid.regex(
  /^[a-z0-9_]+$/i,
  "Only letters, numbers, and underscores are allowed",
);

valid.oneOf(options, msg?)

Requires the value to be one of the allowed options.

valid.oneOf(["admin", "editor", "viewer"], "Role must be one of: ");

valid.custom(fn)

Uses your own validation function.

valid.custom((value) => {
  if (value.startsWith("lavender-")) return null;
  return "Value must start with lavender-";
});

Default Import

You can also import the default object:

import lavenderSTD from "lavender-std";

const name = await lavenderSTD.ask("Name:", [lavenderSTD.valid.required()]);

lavenderSTD.done();

Full Example

import { ask, done, valid as v } from "lavender-std";

async function main() {
  const email = await ask(
    "Email:",
    [v.required("Email is required"), v.email("Invalid email address")],
    "[email protected]",
  );

  const role = await ask(
    "Role (admin/editor/viewer):",
    [
      v.required("Role is required"),
      v.oneOf(["admin", "editor", "viewer"], "Role must be one of: "),
    ],
    "viewer",
  );

  console.log({ email, role });
  done();
}

main();

Package Details

• Package name: lavender-std
• Author: lavender-incognito
• Module type: ESM
• Runtime: Node.js
• License: ISC

License

ISC