[library-name]

npm version CI Coverage License: MIT

Library or package README template: badges, one-line description, features, installation for several package managers, quick start, examples, API overview, configuration, compatibility, versioning, contributing, security and licence. Replace every [bracketed] value and every line marked Example.

[library-name] is a [short category, for example "zero-dependency TypeScript library"] for [what it does, for example "parsing and formatting ISO 8601 durations"].

Features

• Example: Parses every duration form in ISO 8601, including weeks and fractional seconds.
• Example: Zero runtime dependencies, 2.1 kB minified and gzipped, tree-shakeable.
• Example: Fully typed API with no any in public signatures.
• [Feature]: [one-line benefit]
• [Feature]: [one-line benefit]
• [Guarantee, for example "No network access, no global state"]

Installation

Install with your package manager of choice:

npm install [library-name]
pnpm add [library-name]
yarn add [library-name]
bun add [library-name]

[If relevant: for Deno, import from npm:[library-name]. For a CDN, use a pinned version URL such as https://cdn.jsdelivr.net/npm/[library-name]@1.4.2/+esm.]

Peer dependencies: [none / react >= 18].

Quick start

The example below parses a duration, adds it to a date and formats the result:

import { parseDuration, formatDuration, addDuration } from "[library-name]";

const d = parseDuration("P1DT2H30M");
console.log(d.totalSeconds);               // 95400
console.log(addDuration(new Date("2026-01-01T00:00:00Z"), d).toISOString());
// 2026-01-02T02:30:00.000Z
console.log(formatDuration(d, { style: "long" }));
// "1 day, 2 hours, 30 minutes"

Usage examples

Validate user input

Use the non-throwing variant when parsing input you do not control:

import { safeParseDuration } from "[library-name]";

const result = safeParseDuration(form.get("timeout"));
if (!result.ok) {
  showError(result.error.message); // "Expected a designator after '5'"
}

Compare and sort durations

Durations compare by total length, so PT90M equals PT1H30M:

import { compareDurations } from "[library-name]";

items.sort((a, b) => compareDurations(a.duration, b.duration));

[Task name]

[One sentence describing the task, followed by a short code example.]

API overview

Full reference: [https://example.com/docs/api].

Configuration

Options are passed per call. Defaults are chosen to be safe for user input.

Compatibility

Support for a runtime version is dropped only in a major release, after that runtime reaches end of life.

Versioning

This project follows Semantic Versioning 2.0.0:

• Major releases may change or remove public API. Each comes with a migration guide in [docs/migrations/].
• Minor releases add features in a backward-compatible way.
• Patch releases fix bugs without changing documented behaviour.

Public API means the exports listed above and their documented types. Anything marked experimental or exported from [library-name]/internal may change in any release. Deprecated APIs log a warning for at least one minor release before removal. The previous major version receives security fixes for [12] months after a new major is released. See CHANGELOG.md for release history.

Troubleshooting and FAQ

Why does parseDuration("P1M") not equal 30 days? Months and years have no fixed length. They are kept as calendar units and resolved only when added to a specific date with addDuration.

I get ERR_REQUIRE_ESM in an older project. Use the CommonJS entry point with require("[library-name]") on Node.js 20 or later, or upgrade the project to ES modules. Older Node.js versions are not supported.

Does it work in a Content Security Policy without unsafe-eval? Yes. The library never uses eval or new Function.

[Frequent question] [Short answer and a link to the relevant documentation page.]

Alternatives

Contributing

Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct first. To work on the library:

git clone https://github.com/[org]/[library-name].git
cd [library-name] && pnpm install
pnpm test

Good first contributions: [documentation fixes, new locale files, issues labelled good first issue].

Security

Please do not report security vulnerabilities in public issues. Use [GitHub private vulnerability reporting / [email protected]] as described in SECURITY.md. We aim to acknowledge reports within [3] working days.

Licence

MIT © YYYY [Copyright holder]. Third-party notices, if any, are listed in [THIRD_PARTY_NOTICES.md].

Standard and licence note

Based on common industry practice for open-source library READMEs and on Semantic Versioning 2.0.0 (semver.org, CC BY 3.0) for the versioning policy. Original text written for this collection; the example library is fictional. Template licence: MIT.