dir-archiver 2.2.0 → 3.0.1

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changes to Dir Archiver
+
+### Unreleased
+
+* No entries yet.
+
+### 3.0.1 (March 3, 2026)
+
+* Rework README/docs information architecture for fast first-use onboarding.
+* Expand `docs/reference/cli.md` as the canonical CLI command/flag/output reference.
+* Add runnable offline examples and wire `npm run examples:run` into check flows.
+* Add example doc blocks (Goal/Prereqs/Run/Expected output/Safety notes) for each example file.
+* Keep archive runtime behavior and CLI semantics unchanged.
+
+### 3.0.0 (February 28, 2026)
+
+* Rewrite dir-archiver as a bytefold-backed orchestration layer over `open`, `detect`, `list`, `audit`, `extract`, `normalize`, and `write`.
+* Expand format support to the full bytefold `ArchiveFormat` surface (zip/tar/layered codecs).
+* Add runtime adapters for Node.js, Deno, and Bun with unified API behavior.
+* Add strict/agent extraction security enforcement and stable `DirArchiverError.code` contracts.
+* Add CLI v3 contract with schema-driven parsing via `argv-flags`, machine JSON mode, and explicit exit code semantics.
+* Add capability-derived runtime matrix tests, determinism fingerprints, and adversarial security fixtures.
+* Add downstream compatibility gates against released dependencies and `main` branches.
+* Enforce ESM-only, workflow-policy, docs-policy, and runtime-policy gates via `npm run check`.
+* Align dependency source to released `@ismail-elkorchi/bytefold@^0.7.2` (remove local/git-sha dependency path).
+* Bump runtime floor to Node.js >=24 and keep Deno/Bun support through dedicated runtime checks.
+
+### 2.2.0 (January 28, 2026)
+
+* Migrate source to TypeScript with strict compiler options.
+* Build compiled output into `dist/` with declaration files.
+* Add strict ESLint configuration alongside TypeScript typechecking.
+* Require Node.js >=18.
+* CLI exits with a non-zero status when required arguments are missing.
+* Add a CLI smoke test.
+* Skip symlinks by default and add an option to follow them.
+* Exclude entries by name anywhere unless a relative path is specified.
+* Normalize exclude path separators so Windows-style paths work cross-platform.
+* Accept absolute exclude paths when they resolve inside the source tree.
+* Make exclude matching case-insensitive on Windows.
+* Normalize archive entry paths to forward slashes for cross-platform zip compatibility.
+* Traverse entries in deterministic order.
+* Honor explicit true/false values for CLI boolean flags.
+* Improve error handling for archive creation failures.
+* Bump argv-flags to 0.2.1 (inline flag values).
+
+### 2.1.2 (January 28, 2026)
+
+* Add a smoke test suite and npm test script.
+* Add CI to run linting and tests.
+* Declare Node.js >=14 in package metadata.
+
+### 2.1.1 (January 28, 2026)
+
+* Avoid archiving the destination zip when it lives inside the source directory ([#5](https://github.com/Ismail-elkorchi/dir-archiver/issues/5)).
+* `createZip()` now returns a Promise that resolves when the archive is closed ([#13](https://github.com/Ismail-elkorchi/dir-archiver/issues/13)).
+* Bump archiver to 7.0.1 to address dependency deprecation warnings ([#14](https://github.com/Ismail-elkorchi/dir-archiver/issues/14)).
+
+### 2.1.0 (October 25, 2022)
+
+* Add ESLint ([#12](https://github.com/Ismail-elkorchi/dir-archiver/pull/12)).
+* Several enhancements to better support Microsoft Windows ([Diff](https://github.com/Ismail-elkorchi/dir-archiver/compare/2.0.0...v2.1.0)).
+
+### 2.0.0 (September 20, 2022)
+
+* Bump archiver from 5.2.0 to 5.3.1 ([42c30b7](https://github.com/Ismail-elkorchi/dir-archiver/commit/42c30b7a3b7fa0b3101e21559f1774f45d2f06ce)).
+* Add an option to include the base directory in the archive root ([#11](https://github.com/Ismail-elkorchi/dir-archiver/pull/11)).
+
+### 1.2.0 (February 28, 2021)
+
+* Bump archiver from 4.0.2 to 5.2.0 ([b84c347](https://github.com/Ismail-elkorchi/dir-archiver/commit/b84c34731617c57b7c439f15910fcc8fa00747b2)).
+* Make exclude paths relative to run directory ([#4](https://github.com/Ismail-elkorchi/dir-archiver/pull/4)).
+* Remove the destination zip if it exists already ([#7](https://github.com/Ismail-elkorchi/dir-archiver/pull/7)).
+
+### 1.1.2 (July 21, 2020)
+
+* Bump lodash from 4.17.15 to 4.17.19.
+* Bump archiver from 4.0.1 to 4.0.2.
+
+### 1.1.1 (May 14, 2020)
+
+* CLI : prevent execution if the required arguments are missing.
+
+### 1.1.0 (May 13, 2020)
+
+* Add cli script.
+
+### 1.0.1 (May 12, 2020)
+
+* Fix the installation instructions.
+
+### 1.0.0 (May 12, 2020)
+
+* initial release.

package/CONTRACT.md

@@ -0,0 +1,94 @@
+# dir-archiver contract
+
+This document defines the current public behavior contract for `dir-archiver`.
+
+## Runtime support
+
+- Node.js LTS (minimum aligned with bytefold `engines.node`).
+- Latest stable Deno.
+- Latest stable Bun.
+
+## Public operations
+
+- `open(input, options)`
+- `detect(input, options)`
+- `list(input, options)`
+- `audit(input, options)`
+- `extract(input, destination, options)`
+- `normalize(input, destination, options)`
+- `write(source, destination, options)`
+
+Profiles are passed through to bytefold for read/audit/extract/normalize flows (`compat | strict | agent`).
+`WriteOptions.profile` and `WriteOptions.limits` are currently reserved and not forwarded by `write()`.
+
+Detailed option fields and examples are maintained in
+`docs/reference/options.md`.
+
+## Format surface
+
+The package accepts the full bytefold `ArchiveFormat` union:
+
+`zip`, `tar`, `tgz`, `tar.gz`, `gz`, `bz2`, `tar.bz2`, `zst`, `tar.zst`, `br`, `tar.br`, `xz`, `tar.xz`.
+
+### Directory input with single-file codec
+
+When `write()` receives a directory source and the requested format is a single-file codec:
+
+- `gz` -> `tar.gz`
+- `bz2` -> `tar.bz2`
+- `xz` -> `tar.xz`
+- `zst` -> `tar.zst`
+- `br` -> `tar.br`
+
+This conversion is deterministic and reported via `WriteResult.wrappedDirectoryCodec`.
+
+## Determinism rules
+
+- Directory traversal order is lexicographic and stable.
+- Archive entry paths are normalized to `/`.
+- `normalize()` defaults to deterministic mode (`isDeterministic: true`).
+
+## Resource limits
+
+Extraction limits are explicit options:
+
+- `maxEntryBytes`
+- `maxTotalExtractedBytes`
+
+Budget overruns fail with stable code `DIRARCHIVER_RESOURCE_LIMIT`.
+
+## Security model
+
+- Extraction treats archive entries as untrusted.
+- Absolute paths, drive-prefixed paths, and traversal (`..`) are rejected with `DIRARCHIVER_PATH_TRAVERSAL`.
+- Strict/agent extraction runs an audit gate before writing files.
+- Hard links are rejected with `DIRARCHIVER_UNSUPPORTED_ENTRY`.
+- Symlinks are skipped unless explicitly enabled.
+
+## Error code stability
+
+Consumers rely on `DirArchiverError.code`, not message text.
+Current stable codes:
+
+- `DIRARCHIVER_INVALID_SOURCE`
+- `DIRARCHIVER_INVALID_DESTINATION`
+- `DIRARCHIVER_PATH_TRAVERSAL`
+- `DIRARCHIVER_UNSUPPORTED_ENTRY`
+- `DIRARCHIVER_RESOURCE_LIMIT`
+- `DIRARCHIVER_RUNTIME_UNSUPPORTED`
+- `DIRARCHIVER_NORMALIZE_UNSUPPORTED`
+- `DIRARCHIVER_USAGE`
+
+## CLI exit codes
+
+- `0`: success
+- `1`: operational failure
+- `2`: usage/validation failure
+
+Canonical command/flag documentation lives in `docs/reference/cli.md`.
+
+## API surface snapshot oracle
+
+`test/api-snapshot.test.mjs` compares module exports with
+`test/fixtures/api-surface.v3.json`.
+Any intentional API change updates both this contract and the snapshot.

package/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+## Development setup
+
+```sh
+npm ci
+npm run check:fast
+npm run check
+```
+
+## Verification commands
+
+- `npm run check:fast`: lint + Node test suite (no runtime matrix).
+- `npm run check`: full repository gate (policy checks, lint, tests, security tests, runtime matrix).
+
+## Change requirements
+
+- Keep ESM-only packaging.
+- Preserve Node + Deno + Bun compatibility.
+- Add/update tests for behavior changes.
+- Update `CONTRACT.md` for API or guarantee changes.
+
+## Runtime dependency freshness policy
+
+- Keep direct runtime dependencies in `package.json` and `package-lock.json` on the latest published stable versions before every release.
+- Validate with `npm run deps:fresh` (this gate runs in the release workflow).
+- If a dependency is stale, update it in a dedicated PR and run `npm run check`.
+
+## Pull request checklist
+
+- [ ] `npm run check` passes locally
+- [ ] docs updated for user-facing changes
+- [ ] changelog entry added for release-relevant updates

package/README.md

@@ -1,125 +1,74 @@
-[![npm][npm-image]][npm-url] [![license][license-image]][license-url]
-[![changelog][changelog-image]][changelog-url]
+# dir-archiver
 
-# Dir Archiver
-Compress a whole directory (including subdirectories) into a zip file, with options to exclude specific files or directories.
+Archive orchestration for detect/list/audit/extract/normalize/write flows across Node, Deno, and Bun.
 
-# Installation
+## What it is
 
-```sh
-$ npm install dir-archiver
-```
-
-Requires Node.js >=18.
-
-# Usage
-
-## API
+`dir-archiver` provides one API surface for archive operations with explicit safety profiles and stable error codes.
 
-Quick start (async/await):
+## Install
 
-```javascript
-const DirArchiver = require('dir-archiver');
-
-const archive = new DirArchiver(
-  './my-project',
-  './my-project.zip',
-  true,
-  ['node_modules', 'dist', 'nested/secret.txt'],
-  false
-);
-
-await archive.createZip();
+```sh
+npm install dir-archiver
+deno add jsr:@ismail-elkorchi/dir-archiver
 ```
 
-Signature:
+## Quickstart
 
 ```ts
-new DirArchiver(
-  directoryPath: string,
-  zipPath: string,
-  includeBaseDirectory?: boolean,
-  excludes?: string[],
-  followSymlinks?: boolean
-)
-```
-
-Parameters:
-- `directoryPath`: Root folder to archive (must exist).
-- `zipPath`: Destination zip file path (parent directory must exist).
-- `includeBaseDirectory`: When true, the archive contains the source folder as the top-level directory.
-- `excludes`: Names or relative paths to skip. Names without path separators match anywhere; use a relative path
-  (for example, `nested/file.txt`) to target a specific entry. Trailing slashes can target directories (for example, `cache/`).
-  Windows-style backslashes are accepted and normalized. Absolute paths inside the source tree are accepted and converted
-  to relative excludes. Matching is case-insensitive on Windows.
-- `followSymlinks`: Follow symlinks when traversing directories. Default: `false`.
+import { write, detect, extract } from "dir-archiver";
 
-`createZip()` returns a Promise that resolves with the zip path when the archive is finalized and rejects on failure.
-Zip entries always use forward slashes, regardless of OS, and are added in deterministic order.
+await write("./project", "./project.zip", {
+  format: "zip",
+  includeBaseDirectory: true,
+});
 
-## Command Line Interface
+const detected = await detect("./project.zip");
+await extract("./project.zip", "./out", { profile: "strict" });
 
-```sh
-Usage: dir-archiver --src <path-to-directory> --dest <path-to-file>.zip --includebasedir true|false --exclude folder-name file-name.extension
-
-Options:
-  --src             The path of the folder to archive.                            [string][required]
-  --dest            The path of the zip file to create.                           [string][required]
-  --includebasedir  Includes a base directory at the root of the archive.
-                    For example, if the root folder of your project is named
-                    "your-project", setting this option to true will create
-                    an archive that includes this base directory.
-                    If this option is set to false the archive created will
-                    unzip its content to the current directory.                               [bool]
-  --followsymlinks  Follow symlinks when traversing directories.                              [bool]
-  --exclude         A list with the names of the files and folders to exclude. Names without
-                    path separators match anywhere; use a relative path to target a specific
-                    entry. Windows-style backslashes are accepted and normalized.           [array]
+console.log(detected.format);
 ```
 
-Inline values are supported for flags (for example, `--includebasedir=true` or `--exclude=cache`).
+## Options reference
 
-# CLI examples
+- [Options reference](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/reference/options.md)
+- [CLI reference](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/reference/cli.md)
+- [10-minute tutorial: bundle a plugin directory](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/tutorial/bundle-a-plugin.md)
 
-```sh
-# Basic
-dir-archiver --src ./my-project --dest ./my-project.zip
+## When not to use
 
-# Include base directory and exclude node_modules anywhere
-dir-archiver --src ./my-project --dest ./my-project.zip --includebasedir=true --exclude node_modules
+- You only need a low-level parser for a single format.
+- You target CommonJS-only environments or Node < 24.
+- You need interactive archive browsing UI features.
 
-# Exclude a specific path
-dir-archiver --src ./my-project --dest ./my-project.zip --exclude nested/secret.txt
+## When to use
 
-# Windows-style excludes (backslashes are normalized)
-dir-archiver --src . --dest archive.zip --exclude .\\nested\\skip.txt
+- You need one API for detect, list, audit, extract, normalize, and write.
+- You want deterministic normalization for CI pipelines.
+- You need safety profiles for untrusted inputs.
 
-# Follow symlinks
-dir-archiver --src ./my-project --dest ./my-project.zip --followsymlinks=true
-```
+## Compatibility
 
-# Testing
+- Module system: ESM-only.
+- Runtimes: Node `>=24`, current Deno, current Bun.
+- CLI and API contracts are documented in `CONTRACT.md`.
 
-```sh
-$ npm test
-```
+## Links
 
-# Development
+- [Docs index](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/index.md)
+- Reference:
+  - [Reference index](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/reference/index.md)
+  - [Contract](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/CONTRACT.md)
+  - [Security policy](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/SECURITY.md)
+- How-to:
+  - [How-to index](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/how-to/index.md)
+  - [Contributing](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/CONTRIBUTING.md)
+- Explanation: [explanation index](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/explanation/index.md)
+
+## Verification
 
 ```sh
-$ npm install
-$ npm run typecheck
-$ npm run build
-$ npm run lint
+npm run examples:run
+npm run check:fast
+npm run check
 ```
-
-Linting runs TypeScript typechecking and ESLint. CI runs lint and tests on Node 18/20/22 across Linux, macOS, and Windows.
-
-
-
-[changelog-image]: https://img.shields.io/badge/changelog-md-blue.svg?style=flat-square
-[changelog-url]: CHANGELOG.md
-[license-image]: https://img.shields.io/npm/l/dir-archiver.svg?style=flat-square
-[license-url]: LICENSE
-[npm-image]: https://img.shields.io/npm/v/dir-archiver.svg?style=flat-square
-[npm-url]: https://www.npmjs.com/package/dir-archiver

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security policy
+
+## Threat model
+
+- Archive inputs are untrusted by default.
+- Common risks include path traversal, symlink abuse, hard-link abuse, and resource exhaustion.
+- Runtime/feature mismatches are treated as explicit typed failures.
+
+## Safe usage guidance
+
+- Prefer `strict` or `agent` profiles for extraction and audit.
+- Audit untrusted archives before extraction (`audit` + `assertSafe` paths).
+- Set resource limits (`maxEntryBytes`, `maxTotalExtractedBytes`) for hostile inputs.
+
+## Reporting vulnerabilities
+
+Report security issues through GitHub Security Advisories for this repository.
+
+## Disclosure workflow
+
+1. Reproduce and classify impact.
+2. Patch with tests.
+3. Publish release notes and remediation guidance.

package/SUPPORT.md

@@ -0,0 +1,16 @@
+# Support
+
+## Usage questions
+
+Open a GitHub issue and include:
+- runtime (`node`, `deno`, `bun`)
+- package version
+- minimal reproducible example
+
+## Bug reports
+
+Use GitHub issues with expected vs actual behavior and sample command/input.
+
+## Security reports
+
+Follow `SECURITY.md` for private disclosure.

package/dist/cli-args.d.ts

@@ -0,0 +1,24 @@
+import type { ArchiveFormat, ArchiveProfile } from './types.js';
+export type CliCommand = 'open' | 'detect' | 'list' | 'audit' | 'extract' | 'normalize' | 'write';
+export interface ParsedCliArgs {
+    ok: boolean;
+    issues: {
+        code: string;
+        message: string;
+    }[];
+    command: CliCommand | undefined;
+    input: string | undefined;
+    source: string | undefined;
+    output: string | undefined;
+    format: ArchiveFormat | undefined;
+    profile: ArchiveProfile;
+    json: boolean;
+    includeBaseDirectory: boolean;
+    followSymlinks: boolean;
+    exclude: string[];
+    allowSymlinks: boolean;
+    allowHardlinks: boolean;
+    maxEntryBytes: number | undefined;
+    maxTotalExtractedBytes: number | undefined;
+}
+export declare const parseCliArgs: (argv: readonly string[]) => Promise<ParsedCliArgs>;

package/dist/cli-args.js

@@ -0,0 +1,204 @@
+const SUPPORTED_COMMANDS = new Set(['open', 'detect', 'list', 'audit', 'extract', 'normalize', 'write']);
+const SUPPORTED_FORMATS = new Set([
+    'zip',
+    'tar',
+    'tgz',
+    'tar.gz',
+    'gz',
+    'bz2',
+    'tar.bz2',
+    'zst',
+    'tar.zst',
+    'br',
+    'tar.br',
+    'xz',
+    'tar.xz'
+]);
+const SUPPORTED_PROFILES = new Set(['compat', 'strict', 'agent']);
+const CLI_SCHEMA = {
+    source: {
+        type: 'string',
+        flags: ['--source', '--src']
+    },
+    input: {
+        type: 'string',
+        flags: ['--input', '-i']
+    },
+    output: {
+        type: 'string',
+        flags: ['--output', '--dest', '-o']
+    },
+    format: {
+        type: 'string',
+        flags: ['--format']
+    },
+    profile: {
+        type: 'string',
+        flags: ['--profile'],
+        default: 'strict'
+    },
+    json: {
+        type: 'boolean',
+        flags: ['--json'],
+        default: false
+    },
+    includeBaseDirectory: {
+        type: 'boolean',
+        flags: ['--include-base-directory', '--includebasedir'],
+        default: false
+    },
+    followSymlinks: {
+        type: 'boolean',
+        flags: ['--follow-symlinks', '--followsymlinks'],
+        default: false
+    },
+    exclude: {
+        type: 'array',
+        flags: ['--exclude'],
+        default: []
+    },
+    allowSymlinks: {
+        type: 'boolean',
+        flags: ['--allow-symlinks'],
+        default: false
+    },
+    allowHardlinks: {
+        type: 'boolean',
+        flags: ['--allow-hardlinks'],
+        default: false
+    },
+    maxEntryBytes: {
+        type: 'number',
+        flags: ['--max-entry-bytes']
+    },
+    maxTotalExtractedBytes: {
+        type: 'number',
+        flags: ['--max-total-extracted-bytes']
+    }
+};
+let parseArgsPromise;
+const loadParseArgs = () => {
+    parseArgsPromise !== null && parseArgsPromise !== void 0 ? parseArgsPromise : (parseArgsPromise = import('argv-flags').then((moduleExports) => moduleExports.default));
+    return parseArgsPromise;
+};
+export const parseCliArgs = async (argv) => {
+    const parseArgs = await loadParseArgs();
+    const parsed = parseArgs(CLI_SCHEMA, {
+        argv: [...argv]
+    });
+    const issues = parsed.issues.map((issue) => ({
+        code: issue.code,
+        message: issue.message
+    }));
+    const values = parsed.values;
+    const commandToken = parsed.rest[0];
+    const command = resolveCommand(commandToken, values, issues);
+    const profile = resolveProfile(values['profile'], issues);
+    const format = resolveFormat(values['format'], issues);
+    const source = toOptionalString(values['source']);
+    const input = toOptionalString(values['input']);
+    const output = toOptionalString(values['output']);
+    validateCommandRequirements(command, { source, input, output }, issues);
+    return {
+        ok: issues.length === 0,
+        issues,
+        command,
+        source,
+        input,
+        output,
+        format,
+        profile,
+        json: values['json'] === true,
+        includeBaseDirectory: values['includeBaseDirectory'] === true,
+        followSymlinks: values['followSymlinks'] === true,
+        exclude: toStringArray(values['exclude']),
+        allowSymlinks: values['allowSymlinks'] === true,
+        allowHardlinks: values['allowHardlinks'] === true,
+        maxEntryBytes: toOptionalNumber(values['maxEntryBytes']),
+        maxTotalExtractedBytes: toOptionalNumber(values['maxTotalExtractedBytes'])
+    };
+};
+const resolveCommand = (commandToken, values, issues) => {
+    if (typeof commandToken === 'string' && SUPPORTED_COMMANDS.has(commandToken)) {
+        return commandToken;
+    }
+    if (typeof commandToken === 'string' && commandToken.length > 0) {
+        issues.push({
+            code: 'USAGE',
+            message: `Unknown command "${commandToken}".`
+        });
+        return undefined;
+    }
+    const hasSource = typeof values['source'] === 'string';
+    const hasOutput = typeof values['output'] === 'string';
+    if (hasSource && hasOutput) {
+        return 'write';
+    }
+    issues.push({
+        code: 'USAGE',
+        message: 'Missing command.'
+    });
+    return undefined;
+};
+const resolveProfile = (value, issues) => {
+    const normalized = typeof value === 'string' ? value : 'strict';
+    if (!SUPPORTED_PROFILES.has(normalized)) {
+        issues.push({
+            code: 'INVALID_VALUE',
+            message: `Unsupported profile "${String(value)}".`
+        });
+        return 'strict';
+    }
+    return normalized;
+};
+const resolveFormat = (value, issues) => {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    if (!SUPPORTED_FORMATS.has(value)) {
+        issues.push({
+            code: 'INVALID_VALUE',
+            message: `Unsupported format "${value}".`
+        });
+        return undefined;
+    }
+    return value;
+};
+const validateCommandRequirements = (command, values, issues) => {
+    if (!command) {
+        return;
+    }
+    if (command === 'write') {
+        if (!values.source) {
+            issues.push({ code: 'REQUIRED', message: 'write requires --source/--src.' });
+        }
+        if (!values.output) {
+            issues.push({ code: 'REQUIRED', message: 'write requires --output/--dest.' });
+        }
+        return;
+    }
+    if (command === 'extract' || command === 'normalize') {
+        if (!values.input) {
+            issues.push({ code: 'REQUIRED', message: `${command} requires --input.` });
+        }
+        if (!values.output) {
+            issues.push({ code: 'REQUIRED', message: `${command} requires --output.` });
+        }
+        return;
+    }
+    if (!values.input) {
+        issues.push({ code: 'REQUIRED', message: `${command} requires --input.` });
+    }
+};
+const toOptionalString = (value) => {
+    return typeof value === 'string' ? value : undefined;
+};
+const toStringArray = (value) => {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string');
+};
+const toOptionalNumber = (value) => {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+};