@azure-net/node-kit 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Initial framework-independent Node.js toolkit; no runtime dependencies.
+- Typed helpers for enums, IDs, strings, numbers, dates, durations, objects, promises and errors.
+- Domain invariants through `Ensure` and `EnsureError`.
+- Explicit-source environment parsing with `Env`.
+- Typed HTTP envelopes with `ResponseBuilder` and background I/O tracking with `BackgroundTask`.
+- Array-based validation with sync/async execution, nested error trees, custom rules and English/Russian catalogs.
+- Explicit subpath imports only; no catch-all package-root entry point.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pixel1917
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,302 @@
-# Temporary Holding Version
+# @azure-net/node-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-independent Node.js toolkit for the Azure-net ecosystem.
+
+It has no runtime dependencies and does not depend on Svelte, Hono, or Bun APIs.
+The helpers use standard JavaScript and built-in `node:crypto` / `node:util` APIs.
+
+## Installation and imports
+
+Requires Node.js 22 or newer. The test suite also runs on Bun.
+
+```sh
+npm install @azure-net/node-kit
+```
+
+There is no package-root import. Choose the entry point by responsibility:
+
+```ts
+import { StringHelper, EnumHelper } from "@azure-net/node-kit/tools";
+import { Ensure, EnsureError } from "@azure-net/node-kit/domain";
+import { ResponseBuilder } from "@azure-net/node-kit/delivery";
+import { Env, BackgroundTask } from "@azure-net/node-kit/infrastructure";
+import { Validator, rules } from "@azure-net/node-kit/validation";
+import { validationMessagesRu } from "@azure-net/node-kit/validation/messages/ru";
+```
+
+Focused entry points are also available: `/delivery/http`,
+`/infrastructure/environment`, `/infrastructure/background`,
+`/validation/messages` and `/validation/messages/en`.
+Imports from the package root or private `dist` paths are deliberately blocked.
+
+## Development
+
+```sh
+pnpm install
+pnpm build
+pnpm check
+pnpm test
+pnpm test:bun
+```
+
+The build emits ESM JavaScript and TypeScript declarations into `dist`.
+Each build first removes stale generated output. Run `pnpm release:check` for
+a clean build, type checks and Node tests. `npm pack` runs that same gate through
+`prepack`; run `pnpm test:bun` separately to verify Bun before publishing.
+
+## Validation
+
+See the [Validation API reference](VALIDATION.md) for typed rule arrays, sync/async
+validators, localization, nested errors, the full rule catalog, and HTTP integration.
+
+## Domain assertions
+
+```ts
+import { Ensure, EnsureError } from "@azure-net/node-kit/domain";
+import { StringHelper } from "@azure-net/node-kit/tools";
+
+Ensure(
+  StringHelper.isValid(name, { maxLength: 255 }),
+  "Name must contain 1 to 255 characters.",
+);
+
+Ensure(version >= 1, () => new RangeError("Version must be positive."));
+```
+
+`Ensure(condition, error)` returns nothing on success. A failed condition with a
+string throws `EnsureError` with that exact message. A synchronous error factory
+runs only on failure and its Error is thrown unchanged. Exceptions raised by the
+factory also propagate unchanged. The assertion signature supports TypeScript
+narrowing when the condition is a type guard. No inheritance, HTTP status mapping,
+localization or shared state is involved. Both exports are available from
+`@azure-net/node-kit/domain`. `EnsureError` supports the standard `ErrorOptions.cause` option.
+
+## Environment
+
+```ts
+import { Env } from "@azure-net/node-kit/infrastructure/environment";
+import {
+  DurationHelper,
+  NumberHelper,
+  StringHelper,
+} from "@azure-net/node-kit/tools";
+
+const env = new Env(process.env); // Or new Env({ PORT: '3000', DB_PASSWORD: '' }).
+
+const password = env.get("DB_PASSWORD", { allowEmpty: true });
+const port = env.get("PORT", {
+  fallback: "3000",
+  parse: ({ value, invalid }) => {
+    if (!StringHelper.matches(value, /^\d+$/))
+      return invalid("must contain only digits.");
+    const number = Number(value);
+    return NumberHelper.isValid(number, {
+      min: 1,
+      max: 65535,
+      safeInteger: true,
+    })
+      ? number
+      : invalid("must be an integer between 1 and 65535.");
+  },
+}); // number
+
+const timeout = env.get("REQUEST_TIMEOUT", {
+  fallback: "30s",
+  parse: ({ value, invalid }) =>
+    DurationHelper.toSeconds(value) ?? invalid("must be a valid duration."),
+}); // number
+```
+
+`Env` is also exported from `@azure-net/node-kit/infrastructure`.
+The constructor requires an explicit object of `string | undefined` values. It holds
+that object by reference and reads its own properties on each call, without copying,
+caching, mutating it or falling back to global environment variables. Pass a copied
+object if a configuration snapshot is desired. There is no `.env` file loader.
+
+`get` returns a string, or the inferred result of `parse`. Missing values throw an
+Error unless a string fallback is provided. The fallback applies only to `undefined`
+and passes the same validation and parsing. Empty and whitespace-only strings throw
+unless `allowEmpty: true`; that option does not allow missing values. Values are never
+trimmed or coerced automatically. Non-string runtime values throw even with a fallback.
+
+`invalid(message)` throws an Error with the variable name and your message, and has
+return type `never`. Values are not automatically included in errors; do not embed
+secrets in custom messages. Unexpected exceptions from `parse` propagate unchanged.
+No process-global configuration or request state is created.
+
+## Tools
+
+### Durations
+
+```ts
+import { DurationHelper } from "@azure-net/node-kit/tools";
+
+DurationHelper.toSeconds(process.env.REQUEST_TIMEOUT ?? "30s"); // number | null
+DurationHelper.toMilliseconds("1.5m"); // 90000
+DurationHelper.toSeconds("500ms"); // 0.5
+DurationHelper.toSeconds("invalid"); // null
+```
+
+Accepts decimal strings with `ms`, `s`, `m`, `h`, or no unit (seconds).
+Whitespace, signs, exponent notation and numeric inputs are rejected without coercion.
+Values must resolve to whole milliseconds between 0 and 2147483647 inclusive.
+Decimal arithmetic is exact: submillisecond values return `null`, not a rounded result.
+Zero is valid. This parser does not read environment variables, apply defaults or throw
+validation errors. Defaults apply only to absent input at the caller, not malformed input.
+
+```ts
+import {
+  EnumHelper,
+  StringHelper,
+  NumberHelper,
+  DateHelper,
+  UidHelper,
+  ObjectHelper,
+  PromiseHelper,
+  ErrorHelper,
+} from "@azure-net/node-kit/tools";
+
+enum Status {
+  Created = 0,
+  Active = 1,
+}
+const input: unknown = 1;
+EnumHelper.isInEnum(Status, input); // boolean; narrows input to Status
+EnumHelper.getValue(Status, input); // Status | null
+EnumHelper.getValue(Status, "1"); // null, no coercion or name lookup
+
+StringHelper.isValid("Name", { maxLength: 255 });
+StringHelper.isValid(null, {
+  allowNull: true,
+  allowEmpty: true,
+  maxLength: 1000,
+});
+StringHelper.isValid(process.env.DB_PASSWORD, { allowEmpty: true });
+StringHelper.isValid("abc", {
+  minLength: 1,
+  maxLength: 20,
+  pattern: /^[a-z]+$/,
+});
+
+NumberHelper.isPositiveInteger(1);
+NumberHelper.isValid(25, { min: 1, max: 100, safeInteger: true });
+DateHelper.isBefore("2026-01-01", "2026-02-01");
+UidHelper.isValidUuid(UidHelper.generateUuid());
+```
+
+- `EnumHelper` also retains `associateByIndex`, `associateByKey` and `toEntries`.
+  Numeric reverse mappings are excluded. Normal runtime enums and `as const`
+  objects are supported; erased `const enum` declarations are not runtime objects.
+- `StringHelper.isValid` requires a nonblank string by default. `allowNull`,
+  `allowUndefined` and `allowEmpty` are independent. Length uses UTF-16 code units,
+  including surrounding whitespace unless `trim: true` is set. No input is mutated.
+  `matches` does not mutate a regex's `lastIndex`. Predicates return booleans, not errors.
+  Existing `pluralize`, `truncate`, `capitalize`, `decapitalize` and
+  `isEmptyOrWhitespace` methods are retained.
+- `NumberHelper` never coerces values: `''`, `'1'`, `false`, `NaN` and infinities
+  are not valid finite numbers. Integer and safe-integer checks are distinct.
+- `DateHelper` accepts valid Dates, integer millisecond timestamps and strict ISO
+  strings. Date-only and zone-less strings use UTC. Fractions are truncated to
+  milliseconds. Invalid dates return `null` from `compare` and `false` from predicates.
+  `isSame` compares instants, not calendar days. `isBetween` accepts reversed bounds;
+  its fourth argument controls inclusivity. There are no locale settings or formatters.
+- `UidHelper` uses cryptographic randomness with no fallback. `isValidUuid` checks
+  UUID v4. `generateHashId` produces a random hex string, not a cryptographic digest.
+  Timestamp IDs without randomness are only process-local; no random ID method
+  guarantees uniqueness. Invalid generation parameters throw `RangeError`.
+- `ObjectHelper.deepClone` uses native `structuredClone`: cycles, Dates, Maps, Sets,
+  BigInt and typed arrays are supported. Functions cannot be cloned. Custom class
+  prototypes, property descriptors and symbol properties are not preserved; Buffer
+  is not guaranteed to remain Buffer. It is a data clone, not an instance clone.
+  `clone` is shallow and accepts arrays/plain objects only, preserving descriptors.
+  `equals` uses `isDeepStrictEqual`; `compareAsString` remains explicitly JSON-only.
+  `pick`/`omit` use own properties, support symbols and safely handle `__proto__`.
+  `isObjectEmpty` rejects nonobjects and noncollection instances; Map/Set use size.
+  `isAllKeysEmpty` treats nullish leaves and empty containers as empty, supports
+  cycles and deep nesting, and does not invoke getters (accessors count as nonempty).
+- `PromiseHelper.isPromiseLike` checks for callable `then` (including custom thenables).
+- `ErrorHelper.toError` retains existing Error instances and attaches other input as `cause`.
+
+The test suite exercises runtime behavior on Node and Bun, plus compile-time enum
+inference and narrowing. The package does not install process-global request state,
+timers or event listeners.
+
+## HTTP responses
+
+```ts
+import { ResponseBuilder } from "@azure-net/node-kit/delivery";
+
+const response = ResponseBuilder.Created(
+  { id: "1" },
+  {
+    message: "User created",
+    meta: { requestId: "request-1" },
+  },
+);
+
+// Hono route: toJSON returns an object, not an encoded string.
+return c.json(response.toJSON(), response.status);
+// Alternatively, return response.toResponse() for a native Fetch Response.
+```
+
+Every response contains `success`, `status`, `message`, `data`, `meta`, `errors`
+and `code`. Omitted payload fields become `null`. Data, metadata and errors are
+inferred independently. Presets retain literal status types for Hono's `c.json`
+and RPC inference. The package has no Hono dependency.
+
+`new ResponseBuilder(data, options)` defaults to status 200. Presets:
+`Ok` (200), `Created` (201), `Accepted` (202), `BadRequest` (400),
+`Unauthorized` (401), `Forbidden` (403), `NotFound` (404), `Conflict` (409),
+`UnprocessableEntity` (422), `TooManyRequests` (429), `InternalServerError` (500).
+All accept optional data first and options second. Presets fix the status;
+options can customize `message`, `meta`, `errors` and `code`. Error presets
+provide an uppercase snake-case code; pass `code: null` to omit its value.
+Defaults are English HTTP messages; supply your own localized message as needed.
+
+`success` is computed as `status < 400`. Non-null `errors` and `code` on a
+successful response are rejected. Statuses 204, 205, 304 and informational
+statuses are rejected because this builder always emits an envelope with a body.
+The envelope is shallowly frozen; user data is not frozen or copied.
+
+`toResponse(headers?)` sets the HTTP status and uses native `Response.json`.
+Payloads must be JSON-serializable: BigInt and circular references throw during
+serialization. Classes follow standard JSON serialization (for example, Dates
+become strings). Do not pass `JSON.stringify(...)` into Hono's `c.json`.
+
+## Background I/O tasks
+
+```ts
+import { BackgroundTask } from "@azure-net/node-kit/infrastructure";
+
+const background = new BackgroundTask({
+  onError: async (error) => {
+    console.error("Background operation failed", error);
+  },
+});
+
+background.run(() => emailService.sendWelcome(email));
+console.log(background.pendingCount);
+
+// After stopping incoming requests, before closing DB and other dependencies:
+await background.drain();
+```
+
+`run` accepts a task factory and returns `void` immediately. Factories start in
+microtasks and run independently without a concurrency limit. Synchronous throws,
+rejected promises and thenables are sent to the required `onError` callback.
+If that callback throws or rejects, the handler failure and original error are
+reported via `console.error`; normal task failures do not reject `drain`.
+
+`pendingCount` includes asynchronous error handling. `drain` waits for active
+tasks, their error handlers, and tasks added while it waits. Multiple callers may
+drain concurrently. Completed tasks are removed from the registry. Each manager
+owns its own registry; there are no global listeners, timers or shutdown hooks.
+Do not await `drain` from a task or its error handler: it would wait for itself.
+Stop task producers first if drain is used during shutdown; a never-settling task
+will keep it pending. It neither cancels tasks nor forces the process to stay alive.
+
+This is in-process best-effort background I/O, not a durable queue. Process crashes
+can lose tasks. It does not move CPU work to another thread: synchronous work still
+blocks the event loop. Use worker threads for CPU-intensive work and durable queues
+when jobs must survive restarts. Pass captured values rather than keeping entire
+HTTP contexts alive for the duration of a background task.