@ix-xs/node-comfort 1.1.31 → 2.0.0

package/README.md

@@ -1,748 +1,210 @@
-# @ix-xs/node-comfort
-
-
-<div align="center">
-
-
-![Node.js](https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white)
-![JavaScript](https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge&logo=javascript&logoColor=%23F7DF1E)
-![NPM](https://img.shields.io/badge/NPM-%23CB3837.svg?style=for-the-badge&logo=npm&logoColor=white)
-![Github](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)
-
-
-[![npm version](https://badge.fury.io/js/%40ix-xs%2Fnode-comfort.svg)](https://www.npmjs.com/package/@ix-xs/node-comfort)
-[![Downloads](https://img.shields.io/npm/dm/@ix-xs/node-comfort.svg)](https://www.npmjs.com/package/@ix-xs/node-comfort)
-
-
-</div>
-
-
-Small collection of Node.js utilities I use across projects: a logger, a file-system helper, a SQLite wrapper, a runtime type checker, and a few async/process helpers.
-
-
-Everything is plain CommonJS with JSDoc. The package ships with type information for TypeScript and modern editors.
-
-
----
-
-
-## Installation
-
-
-```bash
-npm install @ix-xs/node-comfort
-# or
-yarn add @ix-xs/node-comfort
-# or
-pnpm add @ix-xs/node-comfort
-```
-
-
-Requires Node 20+ (uses `node:sqlite` and `process.loadEnvFile`).
-
-
----
-
-
-## Import and global usage
-
-
-The package exposes a **flat API**: all utilities are directly on the `nodeComfort` object.
-
-
-```js
-const nodeComfort = require("@ix-xs/node-comfort");
-
-
-// Logger
-nodeComfort.log("Hello");
-nodeComfort.log("<% greenBright Success %>");
-
-
-// FS
-const files = nodeComfort.getFilesIn(".", true);
-nodeComfort.createFolder("./dist");
-
-
-// Checker
-if (nodeComfort.isArray(files)) {
-  nodeComfort.log(`<% cyan Found ${files.length} files %>`);
-}
-
-
-// Utils
-await nodeComfort.wait(500);
-nodeComfort.dontCrash();
-
-
-// SQLite
-const db = new nodeComfort.SQLite();
-await db.createTable({
-  name: "users",
-  columns: {
-    id:   { type: "INTEGER", primaryKey: true, autoincrement: true },
-    name: { type: "TEXT", notNull: true },
-  },
-});
-```
-
-
----
-
-
-## Logger
-
-
-Colorized console logger with a minimal markup syntax and optional timestamps.
-
-
-You wrap styles in delimiters (by default `<%` and `%>`):
-
-
-- styles: `bold`, `italic`, `underline`, `overline`
-- colors: `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`, `black`
-- bright: `redBright`, `greenBright`, `yellowBright`, `blueBright`, `magentaBright`, `cyanBright`, `whiteBright`
-- background: `bgRed`, `bgBlue`, etc.
-- RGB: `rgb(255, 0, 0)`
-
-
-### Basic usage
-
-
-```js
-nodeComfort.log("Plain log");
-nodeComfort.log("<% green Success %>");
-nodeComfort.log("<% red bold Error:%> something went wrong");
-nodeComfort.log("<% bgBlue white INFO %> message");
-```
-
-
-Multi-line strings keep indentation and timestamps readable:
-
-
-```js
-nodeComfort.log(`
-<% yellow Multi-line %>
-This is line 2
-This is line 3
-`);
-```
-
-
-### Timestamp and delimiters
-
-
-```js
-// Disable timestamps
-nodeComfort.setTimestamp(false);
-
-
-// Change delimiters if "<%" conflicts with other template syntax
-nodeComfort.setDelimiter({ open: "{{", close: "}}" });
-nodeComfort.log("{{red Hello}} world");
-```
-
-
-### Groups
-
-
-Groups add indentation to related logs.
-
-
-```js
-nodeComfort.group("Startup");
-
-
-nodeComfort.log("Loading config…");
-nodeComfort.log("<% green OK %>");
-
-
-nodeComfort.group("DB");
-nodeComfort.log("Connecting…");
-// ...
-nodeComfort.groupEnd(); // end "DB"
-
-
-nodeComfort.groupEnd(); // end "Startup"
-```
-
-
----
-
-
-## FS
-
-
-File-system helper with safe path resolution, recursive walking, copy/move helpers, and a small watcher abstraction.
-
-
-It resolves relative paths from the **caller file**, not just from `process.cwd()`, which makes it nicer inside libraries.
-
-
-### Path helpers
-
-
-```js
-// Absolute path, even if it doesn't exist yet
-const configPath = nodeComfort.createPath("./config/app.json");
-
-
-// Existing folder/file or undefined
-const folder = nodeComfort.getFolder("./src");
-const file = nodeComfort.getFile("package.json");
-```
-
-
-### Create folders and files
-
-
-```js
-// Folders
-nodeComfort.createFolder("./dist");        // true if created
-nodeComfort.createFolder("./dist", true);  // force recreate
-
-
-// Files
-nodeComfort.createFile("./dist/info.txt", false, "hello");
-nodeComfort.createFile("./dist/data.json", true, { ok: true });
-```
-
-
-### List and delete
-
-
-```js
-// Folders inside a path
-const dirs = nodeComfort.getFoldersIn("./src", true);
-
-
-// Delete folders matching a filter
-nodeComfort.deleteFoldersIn("./tmp", (folder) =>
-  folder.endsWith(".cache"),
-);
-
-
-// Files
-const files = nodeComfort.getFilesIn("./src", true);
-
-
-// Delete files matching a filter
-nodeComfort.deleteFilesIn("./logs", false, (file) =>
-  file.endsWith(".log"),
-);
-```
-
-
-### Copy
-
-
-```js
-// Copy one folder
-nodeComfort.copyFolder({
-  path: "./templates",
-  dest: "./dist/templates",
-  recursive: true,
-  withFiles: true,
-  force: true,
-});
-
-
-// Copy only some folders in a tree
-nodeComfort.copyFoldersIn({
-  path: "./src",
-  dest: "./dist",
-  recursive: true,
-  withFiles: false,
-  filter: (folder) => folder.endsWith("components"),
-});
-
-
-// Copy files
-nodeComfort.copyFilesIn({
-  path: "./src",
-  dest: "./dist",
-  recursive: true,
-  force: true,
-  filter: (file) => file.endsWith(".js"),
-});
-
-
-// Copy a single file
-nodeComfort.copyFile({
-  path: "./src/index.js",
-  dest: "./dist", // or "./dist/index.js"
-  force: true,
-});
-```
-
-
-### Move
-
-
-Move helpers are basically copy + delete.
-
-
-```js
-// Move a folder tree
-nodeComfort.moveFolder({
-  path: "./build",
-  dest: "./dist",
-  recursive: true,
-  withFiles: true,
-  force: true,
-});
-
-
-// Move some folders under a path
-nodeComfort.moveFoldersIn({
-  path: "./tmp",
-  dest: "./archive",
-  recursive: true,
-  withFiles: false,
-  filter: (folder) => folder.includes("session"),
-});
-
-
-// Move files
-nodeComfort.moveFilesIn({
-  path: "./logs",
-  dest: "./logs/archive",
-  recursive: false,
-  force: true,
-  filter: (file) => file.endsWith(".log"),
-});
-
-
-// Move a single file
-nodeComfort.moveFile({
-  path: "./logs/app.log",
-  dest: "./logs/archive/app.log",
-  force: true,
-});
-```
-
-
-### Read and watch
-
-
-```js
-// Read a UTF-8 file
-const content = nodeComfort.readFile("./README.md");
-
-
-// Watch a directory
-const watcher = nodeComfort.watch({
-  path: "./src",
-  recursive: true,
-  filter: (event, file) => file.endsWith(".js"),
-});
-
-
-watcher
-  .on("change", (file) => {
-    nodeComfort.log(`<% cyan File changed: %> ${file}`);
-  })
-  .on("rename", (file) => {
-    nodeComfort.log(`<% yellow File renamed: %> ${file}`);
-  });
-```
-
-
-You can pause, resume and stop watching:
-
-
-```js
-watcher.pause();
-// ...
-watcher.resume();
-// ...
-watcher.stop();
-```
-
-
----
-
-
-## Checker
-
-
-Runtime type-checking helpers. Everything is just a boolean guard that works on any input.
-
-
-```js
-nodeComfort.isArray();        // true[1][2]
-nodeComfort.isArray("nope");        // false
-
-
-nodeComfort.isNumber(42);           // true
-nodeComfort.isNumber(NaN);          // false
-
-
-nodeComfort.isFunction(() => {});   // true
-nodeComfort.isFunction(class {});   // true
-
-
-nodeComfort.isObject({});           // true
-nodeComfort.isObject([]);           // true
-nodeComfort.isObject(null);         // false
-
-
-nodeComfort.isBoolean(false);       // true
-nodeComfort.isString("hello");      // true
-nodeComfort.isUndefined(undefined); // true
-nodeComfort.isNull(null);           // true
-
-
-nodeComfort.isDate(new Date());     // true
-nodeComfort.isMap(new Map());       // true
-nodeComfort.isSet(new Set());       // true
-
-
-nodeComfort.isError(new Error("x")); // true
-nodeComfort.isError({ message: "x" }); // false
-```
-
-
----
-
-
-## Utils
-
-
-Small async and process helpers.
-
-
-### wait(ms)
-
-
-```js
-await nodeComfort.wait(500);
-// code here runs after ~500ms
-```
-
-
-### when(predicate, payload?, options?)
-
-
-Polling helper that emits events until a condition is met.
-
-
-```js
-const task = nodeComfort.when(
-  () => Math.random() > 0.8,
-  { label: "Lucky" },
-  { interval: 200, max: 3, timeout: 5000 },
-);
-
-
-task
-  .on("trigger", (payload) => {
-    nodeComfort.log(`<% green Triggered: %> ${payload.label}`);
-  })
-  .on("timeout", () => {
-    nodeComfort.log("<% red Timeout %>");
-  })
-  .on("error", (err) => {
-    nodeComfort.log(`<% red Error in predicate %>\n${err}`);
-  })
-  .start();
-```
-
-
-- `predicate`: boolean, promise, or function (sync/async) returning a boolean.  
-- `payload`: value passed to listeners on `trigger` / `timeout`.  
-- `options`:
-  - `interval` (ms, default `50`)
-  - `timeout` (ms or `null`)
-  - `max` (number of triggers or `null` for infinite)
-
-
-### dontCrash()
-
-
-Installs process-level safety nets for errors, exits and signals.
-
-
-```js
-nodeComfort.dontCrash();
-
-
-// Or customize:
-nodeComfort.dontCrash()
-  .on("error", (err) => {
-    console.error("Global error:", err);
-    process.exit(1);
-  })
-  .on("exit", (code) => {
-    nodeComfort.log(`<% gray Process exited with code ${code} %>`);
-  })
-  .on("sig", (signal) => {
-    nodeComfort.log(`<% yellow Caught signal ${signal}, exiting… %>`);
-    process.exit(0);
-  });
-```
-
-
-Events:
-
-
-- `"error"` – uncaught exceptions + unhandled rejections  
-- `"exit"` – `process.on("exit")`  
-- `"sig"` – `SIGINT`, `SIGTERM`, `SIGQUIT`  
-- `"beforeExit"` – `process.on("beforeExit")`
-
-
-### JSON helpers
-
-
-```js
-const json = nodeComfort.JSONString({ hello: "world" });
-// pretty-printed with 4 spaces
-
-
-const data = nodeComfort.JSONParse(json);
-```
-
-
----
-
-
-## SQLite
-
-
-Thin wrapper over the built-in `node:sqlite` `DatabaseSync` with a small "model" system and CRUD-style helpers.
-
-
-### Creating an instance
-
-
-```js
-// Default: ./db.sqlite (relative to cwd)
-const db = new nodeComfort.SQLite();
-
-
-// Custom path (folder created if needed)
-const db2 = new nodeComfort.SQLite("data/app.sqlite");
-```
-
-
-The constructor ensures the parent folder exists, and enables WAL journal mode and foreign keys by default.
-
-
-### Defining a table
-
-
-```js
-await db.createTable({
-  name: "users",
-  columns: {
-    id: {
-      type: "INTEGER",
-      primaryKey: true,
-      autoincrement: true,
-    },
-    name: {
-      type: "TEXT",
-      notNull: true,
-    },
-    role: {
-      type: "TEXT",
-      values: ["admin", "user"],
-      defaultValue: "user",
-    },
-    createdAt: {
-      type: "TEXT",
-      defaultValue: new Date().toISOString(),
-    },
-  },
-});
-```
-
-
-Models are kept in memory and used for defaults like ordering.
-
-
-The `columns` property is the new, recommended way. The legacy `options` property is still supported for backward compatibility.
-
-
-### Insert / update / upsert
-
-
-```js
-// Insert a new row
-await db.insert("users", { name: "John" });
-
-
-// Update rows matching a where clause
-await db.update("users", { role: "admin" }, { name: "John" });
-
-
-// Upsert (INSERT with ON CONFLICT DO UPDATE)
-await db.upsert("users", { id: 1, role: "user" }, ["id"]);
-```
-
-
-When `where` or `data.id` is provided, `set` (legacy helper):
-
-
-1. loads the existing row if it exists,  
-2. merges it with `data`,  
-3. inserts or updates depending on whether the row exists.
-
-
-```js
-// Insert
-await db.set("users", { name: "John" });
-
-
-// Upsert by id
-await db.set("users", { id: 1, role: "admin" });
-
-
-// Upsert with custom where
-await db.set("users", { role: "user" }, { name: "John" });
-```
-
-
-### Get / list
-
-
-```js
-// One row or undefined
-const user = await db.get("users", { name: "John" });
-
-
-// Multiple rows with pagination and ordering
-const admins = await db.getAll(
-  "users",
-  { role: "admin" }, // where
-  {
-    limit: 100,
-    offset: 0,
-    orderBy: "createdAt",
-    direction: "DESC",
-  },
-);
-```
-
-
-If the table is not registered, `getAll` returns an empty array.
-
-
-### Delete / clear / count
-
-
-```js
-// Delete rows
-const res = await db.delete("users", { role: "user" });
-// res.ok, res.changes
-
-
-// Delete all rows
-await db.clearTable("users");
-
-
-// Count rows
-const totalUsers = await db.count("users");
-const adminCount = await db.count("users", { role: "admin" });
-```
-
-
-### Indexes and constraints
-
-
-```js
-// Create a composite unique index
-await db.createIndex("UserAuthMethod", {
-  columns: ["provider", "providerUserId"],
-  unique: true,
-});
-
-
-// Create a non-unique index
-await db.createIndex("Post", {
-  columns: ["userId"],
-});
-```
-
-
-```js
-// Table-level constraints
-await db.createTable({
-  name: "UserAuthMethod",
-  columns: {
-    id: { type: "INTEGER", primaryKey: true, autoincrement: true },
-    userId: { type: "INTEGER", notNull: true },
-    provider: { type: "TEXT", notNull: true },
-    providerUserId: { type: "TEXT", notNull: true },
-  },
-  constraints: [
-    {
-      type: "unique",
-      columns: ["provider", "providerUserId"],
-    },
-    {
-      type: "foreignKey",
-      columns: ["userId"],
-      references: { table: "User", columns: ["id"] },
-      onDelete: "CASCADE",
-    },
-  ],
-});
-```
-
-
-### Transactions
-
-
-```js
-const result = await db.transaction(async () => {
-  await db.insert("User", {
-    email: "a@b.com",
-    createdAt: Date.now(),
-  });
-  await db.insert("Profile", {
-    userId: 1,
-    nickname: "John",
-  });
-  return { ok: true };
-});
-```
-
-
-If the callback throws, the transaction is rolled back.
-
-
-### Raw SQL helpers
-
-
-```js
-// Execute a write statement (INSERT/UPDATE/DELETE/CREATE/PRAGMA)
-await db.exec("CREATE INDEX IF NOT EXISTS idx_email ON users (email)");
-
-
-// Execute a query and get one row
-const user = await db.queryOne("SELECT * FROM users WHERE id = ?", );[1]
-
-
-// Execute a query and get all rows
-const users = await db.queryAll("SELECT * FROM users WHERE role = ?", ["admin"]);
-```
-
-
-### Drop and close
-
-
-```js
-await db.deleteTable("users");
-db.close();
-```
-
-
----
-
-
-## License
-
-
-MIT.
+<div align="center">
+
+# node-comfort
+
+**The standard library Node.js deserves.**
+
+Logging, config, validation, HTTP, SQLite, dates, crypto, CLI tools and 500+ helpers.<br>
+One package, zero dependencies, documented right in your editor.
+
+[![npm version](https://img.shields.io/npm/v/@ix-xs/node-comfort.svg)](https://www.npmjs.com/package/@ix-xs/node-comfort)
+[![Downloads](https://img.shields.io/npm/dm/@ix-xs/node-comfort.svg)](https://www.npmjs.com/package/@ix-xs/node-comfort)
+[![CI](https://github.com/ix-xs/node-comfort/actions/workflows/ci.yml/badge.svg)](https://github.com/ix-xs/node-comfort/actions/workflows/ci.yml)
+[![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/@ix-xs/node-comfort?activeTab=dependencies)
+[![Node](https://img.shields.io/node/v/@ix-xs/node-comfort.svg)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+[Documentation](https://ix-xs.github.io/node-comfort/) •
+[Getting started](https://ix-xs.github.io/node-comfort/guide/getting-started.html) •
+[API reference](https://ix-xs.github.io/node-comfort/api/index.html) •
+[Recipes](https://ix-xs.github.io/node-comfort/guide/recipes.html) •
+[Changelog](./CHANGELOG.md)
+
+</div>
+
+---
+
+Most Node.js projects install the same twenty packages before writing a single line of their own: a logger, dotenv, a validation library, an HTTP client, a retry helper, a date library, uuid, bcrypt, a CLI parser, a spinner. Hundreds of transitive dependencies come with them.
+
+Node.js can do most of this on its own now. It ships `fetch`, `Intl`, `node:crypto` and even SQLite. node-comfort is the missing layer on top: one consistent, fully typed API, and nothing else to install.
+
+```js
+const nc = require("@ix-xs/node-comfort");
+
+const config = nc.env.validate({
+  PORT: { type: "port", default: 3000 },
+  DATABASE_URL: { type: "url" },
+});
+
+const db = new nc.SQLite("./data/app.sqlite");
+const github = nc.http.create({ baseURL: "https://api.github.com/", retry: { attempts: 3 } });
+
+const { data: repo } = await github.get("repos/nodejs/node");
+nc.info(`Node.js has <% yellow ${nc.num.abbreviate(repo.stargazers_count)} %> stars`);
+
+nc.sys.onShutdown(() => db.close());
+```
+
+## Install
+
+```bash
+npm install @ix-xs/node-comfort
+```
+
+Node.js 22.13 or newer. That's the first version where `node:sqlite` works without a flag.
+
+## Why node-comfort
+
+- **Zero dependencies.** Built only on Node's own modules. No install scripts, nothing else to audit or keep up to date.
+- **Your editor already knows it.** Every function, parameter and option is typed and documented, with examples. Type `nc.` and look around. It works in plain JavaScript too.
+- **Fast to load.** Namespaces load the first time you use them. Requiring the package takes about 3 ms, and a script that only logs never loads the database or the HTTP client.
+- **Safe by default.** Prototype-pollution-proof objects, scrypt passwords, AES-256-GCM, constant-time comparisons, parameterized SQL, atomic file writes.
+- **One way of doing things.** Durations are always `"5m"` or milliseconds, options always come last, and every error has a stable `code`.
+- **Tested everywhere.** Linux, macOS and Windows, Node.js 22 and 24, TypeScript 5.9, 6 and 7.
+
+## What's inside
+
+| Namespace | What it's for | Often replaces |
+| --- | --- | --- |
+| [Logger](https://ix-xs.github.io/node-comfort/guide/logger.html) | Colorful logs, levels, JSON output, log files with rotation | `chalk`, `pino`, `winston` |
+| [`fs`](https://ix-xs.github.io/node-comfort/guide/fs.html) | Files and folders without try/catch, atomic writes, glob, watch | `fs-extra`, `glob`, `rimraf` |
+| [`checker`](https://ix-xs.github.io/node-comfort/guide/checker.html) | 60+ type guards and validators, `assert` | `is`, `validator` |
+| [`env`](https://ix-xs.github.io/node-comfort/guide/env.html) | `.env` loading, typed and validated configuration | `dotenv`, `envalid` |
+| [`schema`](https://ix-xs.github.io/node-comfort/guide/schema.html) | Data validation with TypeScript inference | `zod`, `yup`, `joi` |
+| [`http`](https://ix-xs.github.io/node-comfort/guide/http.html) | `fetch` with JSON, retries, timeouts, hooks, downloads | `axios`, `got`, `ky` |
+| [`SQLite`](https://ix-xs.github.io/node-comfort/guide/sqlite.html) | CRUD, filters, JSON columns, transactions, migrations | `better-sqlite3` and helpers |
+| [`time`](https://ix-xs.github.io/node-comfort/guide/time.html) | Formatting in any language and time zone, durations, date math, cron | `dayjs`, `ms`, `node-cron` |
+| [`str`](https://ix-xs.github.io/node-comfort/guide/str.html) | Case conversion, slugs, emoji-safe truncation, fuzzy matching, plurals | `lodash`, `slugify`, `leven` |
+| [`num`](https://ix-xs.github.io/node-comfort/guide/num.html) | Exact rounding, statistics, currencies, bytes | `numeral`, `pretty-bytes` |
+| [`arr`](https://ix-xs.github.io/node-comfort/guide/arr.html) | Chunk, group, multi-key sort, paginate, set operations | `lodash` |
+| [`obj`](https://ix-xs.github.io/node-comfort/guide/obj.html) | Deep clone, merge, equal and diff, typed dot paths | `lodash`, `deepmerge`, `dequal` |
+| [`func`](https://ix-xs.github.io/node-comfort/guide/func.html) | Debounce, throttle, memoize, retry with backoff, timeout | `p-retry`, `p-timeout` |
+| [`async`](https://ix-xs.github.io/node-comfort/guide/async.html) | Concurrency limits, queues, mutex, polling | `p-limit`, `p-map`, `p-queue` |
+| [`Cache`](https://ix-xs.github.io/node-comfort/guide/cache.html) | LRU cache with TTL, loaders and statistics | `lru-cache` |
+| [`Emitter`](https://ix-xs.github.io/node-comfort/guide/emitter.html) | Typed events, `waitFor`, async iteration | `mitt`, `emittery` |
+| [`id`](https://ix-xs.github.io/node-comfort/guide/id.html) | UUID v4 and v7, ULID, nanoid, tokens, Snowflakes | `uuid`, `ulid`, `nanoid` |
+| [`crypto`](https://ix-xs.github.io/node-comfort/guide/crypto.html) | Passwords, encryption, JWT, TOTP two-factor codes | `bcrypt`, `jsonwebtoken`, `otplib` |
+| [`cli`](https://ix-xs.github.io/node-comfort/guide/cli.html) | Typed arguments, prompts, menus, spinners, progress bars, tables | `commander`, `inquirer`, `ora` |
+| [`color`](https://ix-xs.github.io/node-comfort/guide/color.html) | Chainable terminal colors, truecolor, gradients, links | `chalk`, `picocolors` |
+| [`sys`](https://ix-xs.github.io/node-comfort/guide/sys.html) | Run commands, `which`, graceful shutdown, platform detection | `execa`, `which` |
+| [`utils`](https://ix-xs.github.io/node-comfort/guide/utils.html) | `wait`, safe JSON, crash guard | |
+| [`errors`](https://ix-xs.github.io/node-comfort/guide/errors.html) | Error classes with stable codes | |
+
+The logger, `fs`, `checker` and `utils` helpers are also available at the top level: `nc.info()`, `nc.readJSON()`, `nc.isEmail()`, `nc.wait()`.
+
+## Importing
+
+```js
+// CommonJS
+const nc = require("@ix-xs/node-comfort");
+const { str, isEmail, info } = require("@ix-xs/node-comfort");
+
+// ES modules
+import nc from "@ix-xs/node-comfort";
+import { slugify } from "@ix-xs/node-comfort/str";   // loads only what it needs
+```
+
+Every namespace has its own entry point (`@ix-xs/node-comfort/http`, `/sqlite`, `/schema`...). In an ES module, importing from these keeps startup lean. See [Performance](https://ix-xs.github.io/node-comfort/guide/performance.html).
+
+TypeScript needs no setup: the types ship with the package.
+
+```ts
+import { schema as s, type Infer } from "@ix-xs/node-comfort";
+
+const User = s.object({ email: s.string().email(), age: s.number().int().optional() });
+type User = Infer<typeof User>; // { email: string; age?: number | undefined }
+```
+
+## A quick tour
+
+**Logs** that look good in a terminal and turn into JSON in production:
+
+```js
+nc.info("Server listening on port 3000").success("Connected to the database");
+nc.log("<% cyan bold Tip:%> press <% bgWhite black  q  %> to quit");
+
+const log = nc.createLogger({ scope: "api", file: { path: "./logs/api.log", maxSize: "10MB", maxFiles: 5 } });
+const reqLog = log.child("request", { fields: { requestId: "a1b2" } });
+```
+
+**Validation** with the type inferred for you:
+
+```js
+const User = nc.schema.object({
+  email: nc.schema.string().trim().email(),
+  age: nc.schema.number().int().min(18).optional(),
+  role: nc.schema.enum(["admin", "user"]).default("user"),
+});
+
+const result = User.safeParse(req.body);
+if (!result.success) return res.status(400).json(result.error.flatten());
+```
+
+**HTTP** on top of `fetch`, with the parts you always end up writing:
+
+```js
+const api = nc.http.create({
+  baseURL: "https://api.example.com/v1/",
+  auth: { bearer: process.env.API_TOKEN },
+  timeout: "10s",
+  retry: { attempts: 3 },
+});
+
+const { data: users } = await api.get("users", { query: { page: 2 } });
+await api.post("users", { name: "Ada" });
+```
+
+**SQLite** without compiling anything, with objects in and objects out:
+
+```js
+const db = new nc.SQLite("./data/app.sqlite");
+
+db.insert("users", { email: "ada@example.com", settings: { theme: "dark" } });
+const admins = db.getAll("users", { role: ["admin", "owner"], age: { gte: 18 } }, { orderBy: "email", limit: 20 });
+db.transaction(() => {
+  db.update("accounts", { balance: 90 }, { id: 1 });
+  db.update("accounts", { balance: 110 }, { id: 2 });
+});
+```
+
+**Dates** in any language and time zone:
+
+```js
+nc.time.setLocale("fr").setTimezone("Europe/Paris");
+nc.time.format(new Date(), "dddd D MMMM YYYY HH:mm"); // "vendredi 11 septembre 2026 14:30"
+nc.time.relative(Date.now() - 3 * 3600e3);            // "il y a 3 heures"
+nc.time.cron("0 9 * * 1-5", sendReport);              // weekdays at 9:00
+```
+
+**Command-line tools** with typed flags, prompts and spinners:
+
+```js
+const { flags } = nc.cli.args({
+  port: { type: "number", short: "p", default: 3000, description: "Port to listen on" },
+}, { version: "1.0.0" });                              // --help and --version for free
+
+const env = await nc.cli.select("Environment?", ["staging", "production"]);
+const spinner = nc.cli.spinner(`Deploying to ${env}`).start();
+spinner.succeed("Deployed");
+```
+
+That's a small part of it. The [guide](https://ix-xs.github.io/node-comfort/guide/introduction.html) walks through every namespace, and the [recipes](https://ix-xs.github.io/node-comfort/guide/recipes.html) show them working together: a small API server, a CLI, a scheduled job.
+
+## Coming from 1.x
+
+2.0 keeps the 1.x API but changes a few behaviors. The main ones:
+
+- Node.js 22.13 or newer is required.
+- SQLite methods throw a `SQLiteError` instead of returning `{ error }`, and `getAll()` no longer adds a default limit and order.
+- `warn` and `error` write to stderr.
+- Deep imports (`@ix-xs/node-comfort/src/...`) are replaced by official entry points (`@ix-xs/node-comfort/str`).
+
+The [migration guide](https://ix-xs.github.io/node-comfort/guide/migration.html) lists every change with before and after examples.
+
+## Contributing
+
+Bug reports, ideas and pull requests are welcome. [CONTRIBUTING.md](./CONTRIBUTING.md) explains how the project is organized. In short: `npm install`, then `npm run check` builds everything and runs the tests.
+
+## License
+
+[MIT](./LICENSE) © ix-xs