{"id":16959835,"url":"https://github.com/jondotsoy/utils-js","last_synced_at":"2025-12-11T18:34:58.099Z","repository":{"id":255741256,"uuid":"853534182","full_name":"JonDotsoy/utils-js","owner":"JonDotsoy","description":"Some utilities to js","archived":false,"fork":false,"pushed_at":"2025-09-24T20:18:23.000Z","size":307,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-09-24T22:23:18.830Z","etag":null,"topics":["get","pipe","set","visit"],"latest_commit_sha":null,"homepage":"https://npmjs.com/@jondotsoy/utils-js","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JonDotsoy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-06T21:13:50.000Z","updated_at":"2025-09-24T20:18:17.000Z","dependencies_parsed_at":"2025-02-20T06:32:26.491Z","dependency_job_id":"8b8a9378-7a5a-4963-ad48-ecc5dc526404","html_url":"https://github.com/JonDotsoy/utils-js","commit_stats":null,"previous_names":["jondotsoy/utils-js"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/JonDotsoy/utils-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonDotsoy%2Futils-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonDotsoy%2Futils-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonDotsoy%2Futils-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonDotsoy%2Futils-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JonDotsoy","download_url":"https://codeload.github.com/JonDotsoy/utils-js/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonDotsoy%2Futils-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013509,"owners_count":26085368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["get","pipe","set","visit"],"created_at":"2024-10-13T22:46:20.069Z","updated_at":"2025-12-11T18:34:58.089Z","avatar_url":"https://github.com/JonDotsoy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# utils-js\n\nSome utilities for JS. Will be util to reduce common logic in your code.\n\n- [visit](#visit)\n- [get](#get)\n- [set](#set)\n- [pick](#pick)\n- [pipe](#pipe)\n- [result](#result)\n- [CleanupTasks](#cleanuptasks)\n- [Bytes](#bytes)\n- [BytesFormat](#bytesformat)\n- [Meter](#meter)\n- [Queue](#queue)\n- [Workspace](#workspace)\n\n## Visit\n\nA generator function that recursively visits nodes in an object, yielding each node that passes the provided test.\n\n**Syntax**\n\n```ts\nvisit(node);\nvisit(node, test);\n```\n\n**Arguments:**\n\n- `node` `\u003cunknown\u003e`: The starting node to visit.\n- `test` `\u003c(node: unknown) =\u003e boolean\u003e`: An optional function that takes a node as input and returns a boolean. If true, the node will be yielded\n\n**Example:**\n\n```ts\nimport { visit } from \"@jondotsoy/utils-js/visit\";\n\nconst v = visit([1, 2, 3]);\nv.next().value; // [1, 2, 3]\nv.next().value; // 1\nv.next().value; // 2\nv.next().value; // 3\n\nconst v = visit(\n  {\n    children: [\n      { type: \"span\", value: \"foo\" },\n      { type: \"block\", children: [{ type: \"span\", value: \"var\" }] },\n    ],\n  },\n  (node) =\u003e node.type === \"span\",\n);\nv.next().value; // {type:\"span\",value:\"foo\"}\nv.next().value; // {type:\"span\",value:\"var\"}\n```\n\n### Visit.getParent\n\nThe Visit.getParent function is a helper method provided by the visit utility. It allows you to retrieve the parent node of a given node during the recursive traversal performed by the visit generator function. This can be useful when you need to access or modify the parent node based on the current node being visited.\n\n**Syntax:**\n\n```ts\nVisit.getParent(node); // =\u003e parent\n```\n\n**Arguments:**\n\n- `node` `\u003cunknown\u003e`: The node element for which to find the parent.\n\n**Return:**\n\nReturns the parent node that contains the provided node. If the node is the root node or has no parent, it returns undefined.\n\n**Example:**\n\n```ts\nfor (const node of visit(\n  { a: { b: { toVisit: true } } },\n  (node) =\u003e node.toVisit,\n)) {\n  visit.getParent(node); // =\u003e { b: { toVisit: true } }\n}\n```\n\n### Visit.getFieldName\n\nThe Visit.getFieldName function is a utility method provided by the visit library. It allows you to retrieve the field name (or key) under which the current node is stored in its parent object during the traversal process.\n\n**Syntax:**\n\n```ts\nVisit.getFieldName(node); // =\u003e string | number | symbol | undefined\n```\n\n**Arguments:**\n\n- `node` `\u003cunknown\u003e`: The node element for which to find the field name.\n\n**Return:**\n\nReturns a string representing the field name of the current node within its parent object. If the node is the root node or the field name cannot be determined, it returns undefined.\n\n**Example:**\n\n```ts\nfor (const node of visit(\n  { a: { b: { toVisit: true } } },\n  (node) =\u003e node.toVisit,\n)) {\n  visit.getFieldName(node); // =\u003e 'b'\n}\n```\n\n## Get\n\nSafely access deeply nested properties in JavaScript/TypeScript objects by following a sequence of keys. The module also exposes type extractors and advanced validators that validate and convert the value when possible, making dynamic data handling safer and more convenient.\n\n**Basic Syntax:**\n\n```ts\nget(obj); // =\u003e unknown | undefined\nget(obj, ...paths); // =\u003e unknown | undefined\n```\n\n**Type Extractors and Advanced Validators:**\n\nThese methods allow you to obtain and validate values of specific types, attempting to convert the value when possible. They return `undefined` if the conversion or validation fails.\n\n- `get.string(obj, ...paths)` → string | undefined\n- `get.number(obj, ...paths)` → number | undefined\n- `get.boolean(obj, ...paths)` → boolean | undefined\n- `get.function(obj, ...paths)` → function | undefined\n- `get.bigint(obj, ...paths)` → bigint | undefined\n- `get.symbol(obj, ...paths)` → symbol | undefined\n- `get.array(obj, ...paths)` → Array\u003cunknown\u003e | undefined\n- `get.date(obj, ...paths)` → Date | undefined\n- `get.numberDate(obj, ...paths)` → number | undefined (timestamp)\n- `get.isoStringDate(obj, ...paths)` → string | undefined (ISO)\n- `get.record(obj, ...paths)` / `get.object(obj, ...paths)` → object | undefined\n- `get.is(test)(obj, ...paths)` → custom validation using a predicate function\n- `get.parse(parser, obj, ...paths)` → advanced extraction and validation using a Zod schema or any object with a `safeParse` method\n\n**Examples:**\n\nBasic access:\n\n```ts\nconst obj = { a: { b: { c: 42 } } };\nget(obj, \"a\", \"b\", \"c\"); // 42\nget(obj, \"a\", \"x\"); // undefined\n```\n\nType extraction and conversion:\n\n```ts\nconst obj = { value: \"123\", created: \"2024-01-01T00:00:00Z\" };\nget.number(obj, \"value\"); // 123\nget.date(obj, \"created\"); // Date instance\nget.isoStringDate(obj, \"created\"); // '2024-01-01T00:00:00.000Z'\n```\n\nCustom validation:\n\n```ts\nconst isEven = (v: unknown): v is number =\u003e\n  typeof v === \"number\" \u0026\u0026 v % 2 === 0;\nconst getEven = get.is(isEven);\nconst obj = { n: 4 };\ngetEven(obj, \"n\"); // 4\n```\n\nAdvanced extraction and validation with Zod or custom parser:\n\n```ts\nimport { z } from \"zod\";\nconst obj = { user: { profile: { age: \"25\" } } };\nconst schema = z.object({ age: z.preprocess(Number, z.number()) });\nget.parse(schema, obj, \"user\", \"profile\"); // { age: 25 }\n\nconst customParser = {\n  safeParse(v: any) {\n    if (v \u0026\u0026 typeof v.foo === \"number\") {\n      return { success: true as const, data: v.foo };\n    }\n    return { success: false as const, error: \"Not a number\" };\n  },\n};\nconst obj2 = { foo: 123 };\nget.parse(customParser, obj2); // 123\n```\n\nThese extractors and validators help you write more robust and safe code, especially when working with dynamic data or complex nested structures.\n\n## Set\n\nSets a value at a specified path within a nested object structure.\n\n**Syntax**\n\n```ts\nset(obj, paths, value);\n```\n\n**Arguments**\n\n- `obj` `\u003cunknown\u003e`: The object to modify.\n- `paths` `\u003cArray\u003cstring | number | symbol\u003e\u003e`: An array of property keys representing the path to the target property.\n- `value` `\u003cunknown\u003e`: The value to set at the specified path.\n\n**Return**\n\nThe modified object.\n\n**Example:**\n\n```ts\nconst obj = { a: {} };\nset(obj, [\"a\", \"b\", \"c\"], 1); // =\u003e { a: { b: { c: 1} } }\n\nconst data = { a: { b: 1 } };\n\nset(data, [\"a\", \"b\"], 2); // =\u003e { a: { b: 2 } }\n\nset(data, [\"a\", \"c\", \"d\"], 3); //=\u003e { a: { b: 2, c: { d: 3 } } }\n```\n\n## Pick\n\nA utility for safely navigating and validating data structures with a chainable API. Returns `undefined` when an operation fails, allowing elegant handling of cases where data doesn't meet expectations.\n\n**Import:**\n\n```ts\nimport { pick } from \"@jondotsoy/utils-js/pick\";\n```\n\n**Syntax:**\n\n```ts\npick(value);\n```\n\n**Arguments:**\n\n- `value` `\u003cunknown\u003e`: The value to wrap and validate.\n\n**Return:**\n\nA Pick instance with chainable validation methods.\n\n**Basic Examples:**\n\n```ts\n// Safe property access\nconst data = { user: { name: \"Alice\", age: 30 } };\nconst name = pick(data).property(\"user\")?.property(\"name\")?.valueOf();\n// name = \"Alice\"\n\n// Type validation\npick(\"hello\").string()?.valueOf(); // \"hello\"\npick(123).number()?.valueOf(); // 123\npick([1, 2, 3]).array()?.valueOf(); // [1, 2, 3]\n\n// Returns undefined on validation failure\npick(123).string(); // undefined\npick(\"text\").number(); // undefined\n```\n\n### Methods\n\n**Type Validators:**\n\n- `.string()` - Validates the value is a string\n- `.number()` - Validates the value is a number\n- `.integer()` - Validates the value is an integer\n- `.bigInt()` - Validates the value is a bigint\n- `.boolean()` - Validates the value is a boolean\n- `.array()` - Validates the value is an array\n- `.record()` - Validates the value is an object\n- `.native()` - Validates the value is a native JS type (string, number, boolean, array, or object)\n- `.date()` - Validates the value is a valid Date object (returns DatePick)\n- `.undefined()` - Validates the value is undefined\n- `.null()` - Validates the value is null\n- `.symbol()` - Validates the value is a symbol\n\n**Navigation \u0026 Transformation:**\n\n- `.property(key)` - Accesses an object property\n- `.pipe(transform)` - Applies a transformation function\n- `.find(filter)` - Finds an element in an array\n- `.filter(filter)` - Filters array elements\n- `.every(validator)` - Validates all array elements\n- `.oneOf(validators)` - Tries multiple validators\n- `.enum(values)` - Validates value is in a set of allowed values\n- `.valueOf()` - Returns the current value\n\n**String Validators:**\n\n- `.startsWith(prefix)` - Validates string starts with prefix\n- `.endsWith(suffix)` - Validates string ends with suffix\n- `.includes(search)` - Validates string/array/record contains element\n- `.length(length)` - Validates exact length\n- `.min(minValue)` - Validates minimum length/value\n- `.max(maxValue)` - Validates maximum length/value\n- `.regexp(pattern, flags?)` - Validates string matches regex\n- `.uppercase()` - Validates all alphabetic characters are uppercase\n- `.lowercase()` - Validates all alphabetic characters are lowercase\n- `.email()` - Validates email format\n- `.url()` - Validates URL format\n- `.trim()` - Removes whitespace from start and end\n- `.toUpperCase()` - Transforms to uppercase\n- `.toLowerCase()` - Transforms to lowercase\n\n**Number Validators:**\n\n- `.gt(other)` - Validates greater than\n- `.gte(other)` - Validates greater than or equal\n- `.lt(other)` - Validates less than\n- `.lte(other)` - Validates less than or equal\n- `.eq(other)` - Validates strict equality\n- `.between(min, max)` - Validates within range\n- `.positive()` - Validates positive number\n- `.negative()` - Validates negative number\n- `.multipleOf(divisor)` - Validates multiple of divisor\n- `.even()` - Validates even number\n- `.odd()` - Validates odd number\n\n**Array Validators:**\n\n- `.minLength(min)` - Validates minimum array length\n- `.maxLength(max)` - Validates maximum array length\n- `.notEmpty()` - Validates array is not empty\n- `.first()` - Gets first element\n- `.last()` - Gets last element\n- `.at(index)` - Gets element at index\n\n**Record Validators:**\n\n- `.hasKey(key)` - Validates object has key\n- `.hasKeys(keys)` - Validates object has all keys\n- `.keys()` - Gets object keys as ArrayPick\n- `.values()` - Gets object values as ArrayPick\n- `.minKeys(min)` - Validates minimum number of keys\n- `.maxKeys(max)` - Validates maximum number of keys\n\n**Advanced Examples:**\n\n```ts\n// Enum validation\nconst status = pick({ status: \"active\" })\n  .property(\"status\")\n  ?.enum([\"active\", \"inactive\", \"pending\"])\n  ?.valueOf();\n// status = \"active\"\n\n// Transformation pipeline\nconst port = pick({ port: \"3000\" })\n  .property(\"port\")\n  ?.string()\n  ?.pipe((str) =\u003e parseInt(str, 10))\n  .valueOf();\n// port = 3000\n\n// Array validation\nconst tags = pick({ tags: [\"typescript\", \"javascript\"] })\n  .property(\"tags\")\n  ?.every((v) =\u003e v.string())\n  ?.valueOf();\n// tags = [\"typescript\", \"javascript\"]\n\n// Flexible type validation\nconst timeout = pick({ timeout: 5000 })\n  .property(\"timeout\")\n  ?.oneOf([(v) =\u003e v.string(), (v) =\u003e v.number()])\n  ?.valueOf();\n// timeout = 5000\n\n// Array filtering\nconst users = [\n  { name: \"Alice\", active: true },\n  { name: \"Bob\", active: false },\n];\nconst activeUsers = pick(users)\n  .filter((user: any) =\u003e user.active)\n  ?.valueOf();\n// activeUsers = [{ name: \"Alice\", active: true }]\n\n// String validation with regex\nconst email = pick({ email: \"user@example.com\" })\n  .property(\"email\")\n  ?.string()\n  ?.regexp(/^[\\w.-]+@[\\w.-]+\\.\\w+$/)\n  ?.valueOf();\n// email = \"user@example.com\"\n\n// Date validation with range\nconst validDate = pick({ createdAt: new Date(\"2024-06-15\") })\n  .property(\"createdAt\")\n  ?.date()\n  ?.after(new Date(\"2024-01-01\"))\n  ?.before(new Date(\"2024-12-31\"))\n  ?.valueOf();\n// validDate = Date object if within range\n\n// Number range validation\nconst age = pick({ age: 25 })\n  .property(\"age\")\n  ?.number()\n  ?.gte(18)\n  ?.lte(65)\n  ?.valueOf();\n// age = 25\n\n// String length and case validation\nconst username = pick({ username: \"john_doe\" })\n  .property(\"username\")\n  ?.string()\n  ?.min(3)\n  ?.max(20)\n  ?.lowercase()\n  ?.valueOf();\n// username = \"john_doe\"\n```\n\n### DatePick\n\n`DatePick` is a specialized class for date validation, automatically returned by `.date()`:\n\n**Methods:**\n\n- `.after(minDate)` - Validates date is after minimum date\n- `.before(maxDate)` - Validates date is before maximum date\n- `.between(minDate, maxDate)` - Validates date is within range\n\n**Example:**\n\n```ts\nconst data = { createdAt: new Date(\"2024-01-01\") };\n\n// Validate Date object (does not convert timestamps or strings)\nconst date = pick(data).property(\"createdAt\")?.date()?.valueOf();\n// date = Date object\n\n// Validate date range\nconst inRange = pick(data)\n  .property(\"createdAt\")\n  ?.date()\n  ?.between(new Date(2024, 0, 1), new Date(2024, 11, 31))\n  ?.valueOf();\n// inRange = Date object if in 2024\n```\n\n**Utilities:**\n\nThe `pick.utils` namespace exposes type validation functions for independent use:\n\n```ts\npick.utils.isString(value); // boolean\npick.utils.isNumber(value); // boolean\npick.utils.isBoolean(value); // boolean\npick.utils.isArray(value); // boolean\npick.utils.isRecord(value); // boolean\npick.utils.isSymbol(value); // boolean\npick.utils.hasOwnProperty(obj, key); // boolean\npick.utils.includes(array, value); // boolean\n```\n\nFor complete API documentation and more examples, see [src/pick/README.md](src/pick/README.md).\n\n## Pipe\n\n\u003e Inspired by [tc39/proposal-pipeline-operator](https://github.com/tc39/proposal-pipeline-operator).\n\nAllows you to chain operations in a readable and simple way, supporting both synchronous and asynchronous functions. The pipeline type adapts automatically according to the value returned by each operation.\n\n**Import:**\n\n```ts\nimport { pipe } from \"@jondotsoy/utils-js/pipe\";\n```\n\n**Syntax**\n\n```ts\npipe(initialValue).value();\npipe(initialValue).pipe(operator).value();\npipe(initialValue).pipe(operator).pipe(operator).value();\n// ...and so on\n\n// If you use `await` directly, you do not need to call `.value()`:\nawait pipe(initialValue);\nawait pipe(initialValue).pipe(operator);\nawait pipe(initialValue).pipe(operator).pipe(operator);\n// ...and so on\n```\n\n**Basic usage:**\n\n```ts\nconst sum = (v: number) =\u003e (a: number) =\u003e a + v;\n\n// Synchronous operations\nconst res = pipe(3)\n  .pipe(sum(1))\n  .pipe((a) =\u003e a * 2)\n  .value(); // =\u003e 8\n\n// Asynchronous or mixed operations\nconst asyncSum = (v: number) =\u003e async (a: number) =\u003e a + v;\n\nconst result = await pipe(3)\n  .pipe(asyncSum(2))\n  .pipe((a) =\u003e a * 2)\n  .value(); // =\u003e 10\n```\n\n**API:**\n\n- `pipe(initialValue)`\n  - Creates a pipeline with the initial value (can be sync or a promise).\n- `.pipe(fn)`\n  - Chains a function that receives the previous value and returns a new value or a promise.\n  - If any function returns a promise, the pipeline becomes asynchronous automatically.\n- `.value()`\n  - Returns the final value (or a promise if any operation was asynchronous).\n\n**Additional examples:**\n\n```ts\n// Mixed chaining\nconst res = await pipe(1)\n  .pipe((a) =\u003e a + 1)\n  .pipe(async (a) =\u003e a * 3)\n  .pipe((a) =\u003e a - 2);\n// =\u003e 4\n\n// Only synchronous\npipe(5)\n  .pipe((a) =\u003e a * 2)\n  .pipe((a) =\u003e a + 1)\n  .value(); // =\u003e 11\n```\n\n**Types:**\n\n- The type returned by `.pipe()` and `.value()` automatically adjusts according to the value type (sync/async).\n- You do not need to import from `pipe/async`, the main `pipe` handles both cases.\n\n## result\n\n\u003e Inspiring on [arthurfiorette/proposal-safe-assignment-operator](https://github.com/arthurfiorette/proposal-safe-assignment-operator)\n\nCapture the result of an expression and return it as a tuple with success status, error, and value. Provides type-safe error handling without try-catch blocks.\n\n```ts\nimport { result } from \"@jondotsoy/utils-js/result\";\n\nconst asyncExpression = () =\u003e fetch(\"https://example.com\");\n\nconst [ok, error, response] = await result(asyncExpression);\n\nif (!ok) {\n  console.error(error);\n  return;\n}\n\nconsole.log(response);\n```\n\n**Syntax**\n\n```ts\nconst [ok, error, value] = result(expression);\nconst [ok, error, value] = await result(asyncExpression);\nconst [ok, error, value] = result(fn, ...args); // Function with arguments\n```\n\n**Arguments**\n\n- `expression` `\u003c() =\u003e unknown | Promise\u003cunknown\u003e\u003e`: A function that returns a value or promise.\n- `asyncExpression` `\u003c() =\u003e Promise\u003cunknown\u003e\u003e`: A function that returns a promise.\n- `fn` `\u003c(...args: any[]) =\u003e unknown | Promise\u003cunknown\u003e\u003e`: A function to call with provided arguments.\n- `...args` `\u003cany[]\u003e`: Arguments to pass to the function.\n\n**Return**\n\nA tuple containing:\n\n- `ok` `\u003cboolean\u003e`: Success status (true if successful, false if error)\n- `error` `\u003cError | null\u003e`: The error (null if successful)\n- `value` `\u003cT | null\u003e`: The result value (null if error)\n\n**Examples**\n\n**Basic synchronous function:**\n\n```ts\nimport { result } from \"@jondotsoy/utils-js/result\";\n\nconst [ok, error, data] = result(() =\u003e JSON.parse('{\"key\": \"value\"}'));\n\nif (!ok) {\n  console.error(\"Parse failed:\", error.message);\n  return;\n}\n\nconsole.log(\"Parsed data:\", data); // { key: \"value\" }\n```\n\n**Asynchronous function:**\n\n```ts\nconst [ok, error, response] = await result(async () =\u003e {\n  const res = await fetch(\"https://api.example.com/data\");\n  return res.json();\n});\n\nif (!ok) {\n  console.error(\"API call failed:\", error);\n  return;\n}\n\nconsole.log(\"API data:\", response);\n```\n\n**Function with arguments:**\n\n```ts\nconst [ok, error, parsed] = result(JSON.parse, '{\"name\": \"John\"}');\n\nif (!ok) {\n  console.error(\"JSON parsing failed:\", error.message);\n  return;\n}\n\nconsole.log(\"User:\", parsed.name); // \"John\"\n```\n\n**Direct Promise handling:**\n\n```ts\nconst [ok, error, value] = await result(Promise.resolve(42));\n\nif (ok) {\n  console.log(\"Value:\", value); // 42\n}\n```\n\n**Alternative exports:**\n\n```ts\nimport { Result, ok, error } from \"@jondotsoy/utils-js/result\";\n\n// Create results manually\nconst success = ok(42); // [true, null, 42]\nconst failure = error(new Error()); // [false, Error, null]\n\n// Use Result class methods\nconst [isOk, err, val] = Result.try(() =\u003e riskyOperation());\n```\n\n## CleanupTasks\n\n**syntax**\n\n```ts\nconst cleanupTasks = new CleanupTasks();\nawait using cleanupTasks = new CleanupTasks();\n```\n\n**Return**\n\nInstance of `CleanupTasks` class.\n\n**Example**\n\n```ts\nawait using cleanupTasks = new CleanupTasks();\n\ncleanupTasks.add(() =\u003e myCleanupTask());\n\nawait cleanupTasks.cleanup();\n```\n\n## Bytes\n\nA utility class for converting and formatting byte values in different units (byte, kilobyte, megabyte, gigabyte, terabyte, petabyte). Supports aliases and plural forms for units, as well as parsing from strings.\n\n**Syntax:**\n\n```ts\nimport { Bytes } from \"@jondotsoy/utils-js/bytes\";\n\nconst bytes = new Bytes(1024); // 1024 bytes\n```\n\n### Methods\n\n| Method                              | Description                                                                 |\n| ----------------------------------- | --------------------------------------------------------------------------- |\n| `toBytes()`                         | Returns the value in bytes.                                                 |\n| `toKilobytes()`                     | Returns the value in kilobytes.                                             |\n| `toMegabytes()`                     | Returns the value in megabytes.                                             |\n| `toGigabytes()`                     | Returns the value in gigabytes.                                             |\n| `toTerabytes()`                     | Returns the value in terabytes.                                             |\n| `toPetabytes()`                     | Returns the value in petabytes.                                             |\n| `toLocaleString(locale?, options?)` | Returns a human-readable string (e.g., '1 MB'), accepts formatting options. |\n| `static from(value, unit?)`         | Creates a Bytes instance from a number and unit, or from a string.          |\n\n### Supported units\n\n- `byte`, `kilobyte`, `megabyte`, `gigabyte`, `terabyte`, `petabyte`\n- Aliases: `b`, `kb`, `mb`, `gb`, `tb`, `pb`\n- Plurals: `bytes`, `kilobytes`, etc.\n\n### Examples\n\n**Convert between units:**\n\n```ts\nconst bytes = new Bytes(1048576); // 1 MB\nbytes.toKilobytes(); // 1024\nbytes.toMegabytes(); // 1\nbytes.toGigabytes(); // 0.0009765625\n```\n\n**Create Bytes from number and unit:**\n\n```ts\nconst kb = Bytes.from(1, \"kilobyte\");\nkb.toBytes(); // 1024\n\nconst mb = Bytes.from(2, \"mb\");\nmb.toBytes(); // 2097152\n```\n\n**Create Bytes from string:**\n\n```ts\nconst b1 = Bytes.from(\"1kb\");\nb1.toBytes(); // 1024\n\nconst b2 = Bytes.from(\"2 MB\");\nb2.toBytes(); // 2097152\n```\n\n**Format as a human-readable string:**\n\n```ts\nconst bytes = new Bytes(123456789);\nbytes.toLocaleString(\"en-US\"); // '117.74 MB'\nbytes.toLocaleString(\"de-DE\"); // '117,74 MB'\n// With options:\nbytes.toLocaleString(\"en-US\", { unit: \"megabyte\", maximumFractionDigits: 1 }); // '117.7 MB'\n```\n\n**Error handling for invalid units:**\n\n```ts\nBytes.from(1, \"invalidUnit\"); // Throws: Invalid unit type: invalidUnit\nBytes.from(\"10zz\"); // Throws: Invalid unit type: zz\n```\n\n## BytesFormat\n\nA utility class for formatting byte values into human-readable strings with automatic or fixed units, supporting localization and custom formatting options.\n\n**Syntax:**\n\n```ts\nimport { BytesFormat } from \"@jondotsoy/utils-js/bytes-format\";\n\nconst formatter = new BytesFormat(\"en-US\");\nformatter.format(1048576); // '1 MB'\n```\n\n### Constructor\n\n```ts\nnew BytesFormat(locale?: string, options?: BytesFormatOptions)\n```\n\n- `locale`: Optional. A BCP 47 language tag (e.g., 'en-US', 'de-DE').\n- `options`: Optional. Formatting options:\n  - `unit`: Force a specific unit (e.g., 'megabyte'), or use 'auto' (default).\n  - `unitDisplay`: 'short' | 'long' | 'narrow' (default: 'short').\n  - `maximumFractionDigits`: Number of decimal places (default: 2).\n  - `maximumSignificantDigits`: Number of significant digits.\n\n### Methods\n\n| Method      | Description                                                  |\n| ----------- | ------------------------------------------------------------ |\n| `format(n)` | Formats the number of bytes as a localized string with unit. |\n\n### Examples\n\n**Automatic unit selection:**\n\n```ts\nconst f = new BytesFormat(\"en-US\");\nf.format(2048); // '2 kB'\nf.format(1048576); // '1 MB'\nf.format(512); // '512 byte'\n```\n\n**Force a specific unit:**\n\n```ts\nconst f = new BytesFormat(\"en-US\", { unit: \"megabyte\" });\nf.format(1048576); // '1 MB'\nf.format(2048); // '0 MB'\n```\n\n**Custom unit display:**\n\n```ts\nnew BytesFormat(\"en-US\", { unitDisplay: \"long\" }).format(2048); // '2 kilobytes'\nnew BytesFormat(\"en-US\", { unitDisplay: \"narrow\" }).format(2048); // '2kB'\n```\n\n**Custom decimal places:**\n\n```ts\nnew BytesFormat(\"en-US\", { maximumFractionDigits: 1 }).format(1536); // '1.5 kB'\nnew BytesFormat(\"en-US\", { maximumFractionDigits: 0 }).format(1536); // '2 kB'\n```\n\n**Localization:**\n\n```ts\nnew BytesFormat(\"de-DE\").format(123456789); // '117,74 MB'\n```\n\n## Meter\n\nA library for parsing, converting, and formatting International System (SI) length units with localization support.\n\n**Import:**\n\n```ts\nimport { Meter } from \"@jondotsoy/utils-js/meter\";\nimport { MeterFormat } from \"@jondotsoy/utils-js/meter\";\n```\n\n### Features\n\n- Parse strings with units (e.g., \"2.5 km\", \"100 cm\")\n- Automatic conversion between units\n- Localized formatting using `Intl.NumberFormat`\n- Support for multiple languages with automatic pluralization\n- Short and long unit forms\n\n### Supported Units\n\n| Unit       | Short | Long       | Factor         |\n| ---------- | ----- | ---------- | -------------- |\n| Kilometer  | km    | kilometer  | 1,000,000 mm   |\n| Hectometer | hm    | hectometer | 100,000 mm     |\n| Decameter  | dam   | decameter  | 10,000 mm      |\n| Meter      | m     | meter      | 1,000 mm       |\n| Decimeter  | dm    | decimeter  | 100 mm         |\n| Centimeter | cm    | centimeter | 10 mm          |\n| Millimeter | mm    | millimeter | 1 mm           |\n| Micrometer | µm    | micrometer | 0.001 mm       |\n| Nanometer  | nm    | nanometer  | 0.000001 mm    |\n| Picometer  | pm    | picometer  | 0.000000001 mm |\n\n### Basic Usage\n\n**Parsing values:**\n\n```ts\n// Parse from string with unit\nconst distance1 = Meter.parse(\"2.5 km\");\nconsole.log(distance1.millimeter); // 2500000\n\n// Parse from number (assumes millimeters)\nconst distance2 = Meter.parse(1000);\nconsole.log(distance2.millimeter); // 1000\n\n// Different unit formats\nMeter.parse(\"1cm\"); // 10 mm\nMeter.parse(\"12 km\"); // 12000000 mm\nMeter.parse(\"2.5 meter\"); // 2500 mm\n```\n\n**Formatting values:**\n\n```ts\n// Simple format\nMeter.parse(\"2m\").toLocaleString(); // \"2 m\"\n\n// Long format (full names)\nMeter.parse(\"2m\").toLocaleString(undefined, { unitDisplay: \"long\" });\n// \"2 meters\"\n\n// Different locales\nMeter.parse(\"2500mm\").toLocaleString(\"en\", { unitDisplay: \"long\" });\n// \"2.5 meters\"\n\nMeter.parse(\"5000mm\").toLocaleString(\"ja-JP\", { unitDisplay: \"long\" });\n// \"5メートル\"\n```\n\n**Conversion between units:**\n\n```ts\nconst distance = Meter.parse(\"2500 m\");\nconst result = distance.toLocaleString(\"en\", {\n  unit: \"kilometer\",\n  unitDisplay: \"long\",\n});\nconsole.log(result); // \"2.5 kilometers\"\n```\n\n### MeterFormat\n\nCreates a reusable formatter for consistent formatting:\n\n```ts\nconst formatter = new MeterFormat(\"es-CL\", { unitDisplay: \"long\" });\n\nformatter.format(\"1km\"); // \"1 kilometer\"\nformatter.format(\"3 cm\"); // \"3 centimeters\"\nformatter.format(2500); // \"2.5 meters\"\n```\n\n**Options:**\n\n- `locale`: Locale to use (e.g., 'es-CL', 'en', 'ja-JP')\n- `unitDisplay`: 'short' | 'long' - Unit format\n- `unit`: Fixed unit to use (e.g., 'kilometer', 'meter')\n- `unitAllow`: Array of allowed units for automatic selection\n\n**Examples:**\n\n```ts\n// Fixed unit\nMeter.parse(\"2500m\").toLocaleString(\"es-CL\", {\n  unit: \"kilometer\",\n  unitDisplay: \"long\",\n});\n// \"2.5 kilometers\"\n\n// Restrict allowed units\nconst formatter = new MeterFormat(\"es-CL\", {\n  unitAllow: [\"km\", \"m\", \"cm\"],\n  unitDisplay: \"long\",\n});\nformatter.format(\"5000mm\"); // \"5 meters\" (doesn't use millimeters)\n```\n\nFor complete API documentation and more examples, see [src/meter/README.md](src/meter/README.md).\n\n## Queue\n\nA lightweight asynchronous message queue system with support for pluggable storage, keep-alive acknowledgments, TTL (Time-to-Live) message expiration, and manual message confirmation. Perfect for background job processing, task coordination, and reliable message distribution with at-least-once delivery semantics.\n\n**Import:**\n\n```ts\nimport { Queue } from \"@jondotsoy/utils-js/queue\";\n\n// For persistent storage (browser environments)\nimport { IndexedDBStore } from \"@jondotsoy/utils-js/queue/store/indexeddb-store\";\n\n// For worker-based storage (browser and Node.js)\nimport { WorkerStore } from \"@jondotsoy/utils-js/queue/store/worker-store\";\n```\n\n### Basic Usage\n\n**Simple message processing with manual acknowledgment:**\n\n```ts\nconst queue = new Queue();\n\n// Add messages\nawait queue.add({ task: \"send-email\", to: \"user@example.com\" });\nawait queue.add({ task: \"process-image\", id: 123 });\n\n// Process messages with explicit acknowledgment\nfor await (const message of queue) {\n  try {\n    console.log(\"Processing:\", message);\n    await processMessage(message);\n\n    // Acknowledge successful processing - required for deletion\n    queue.ack(message);\n  } catch (error) {\n    // Don't acknowledge - message will be reclaimed\n    console.error(\"Processing failed:\", error);\n  }\n}\n```\n\n**Concurrent workers:**\n\n```ts\nconst queue = new Queue();\n\nconst worker = (name) =\u003e async () =\u003e {\n  for await (const job of queue) {\n    try {\n      console.log(`${name} processing:`, job);\n      await simulateWork(job);\n      queue.ack(job); // Acknowledge successful processing\n    } catch (error) {\n      console.error(`${name} failed:`, error);\n      // Don't acknowledge - message will be reclaimed by another worker\n    }\n  }\n};\n\n// Both workers process different messages concurrently\nawait Promise.all([worker(\"Worker-1\")(), worker(\"Worker-2\")()]);\n```\n\n**With persistent storage (IndexedDB):**\n\n```ts\nimport { IndexedDBStore } from \"@jondotsoy/utils-js/queue/store/indexeddb-store\";\n\n// Messages persist across browser sessions\nconst queue = new Queue({\n  store: new IndexedDBStore(\"my-app-queue\"),\n});\n\nawait queue.add({ task: \"process-order\", orderId: \"123\" });\n\nfor await (const job of queue) {\n  console.log(\"Processing:\", job);\n  // Messages are automatically persisted to IndexedDB\n  queue.ack(job);\n}\n```\n\n**With worker-based storage (non-blocking):**\n\n```ts\nimport { WorkerStore } from \"@jondotsoy/utils-js/queue/store/worker-store\";\n\n// Create worker that handles storage operations\nconst worker = new Worker(\"/worker-store-backend.js\");\nconst queue = new Queue({\n  store: new WorkerStore(worker),\n});\n\nawait queue.add({ task: \"cpu-intensive-work\", data: largeDataset });\n\nfor await (const job of queue) {\n  console.log(\"Processing:\", job);\n  // Storage operations happen in worker thread - main thread stays responsive\n  queue.ack(job);\n}\n\n// Health check\nconst response = await queue.store.ping(); // \"pong\"\n\n// Cleanup\nawait queue.close();\nworker.terminate();\n```\n\n**With TTL (Time-to-Live) expiration:**\n\n```ts\nimport { IndexedDBStore } from \"@jondotsoy/utils-js/queue/store/indexeddb-store\";\n\nconst queue = new Queue({\n  store: new IndexedDBStore(\"task-queue\"),\n});\n\n// Add message with TTL (expires in 1 hour)\nawait queue.add(\n  { task: \"send-notification\", userId: \"123\" },\n  { ttl: 60 * 60 }, // 3600 seconds = 1 hour\n);\n\n// Add urgent task (expires in 5 minutes)\nawait queue.add(\n  { task: \"urgent-cleanup\", resource: \"/tmp\" },\n  { ttl: 5 * 60 }, // 300 seconds = 5 minutes\n);\n\n// Expired messages are automatically filtered out and cleaned up\n// Manual cleanup also available: await queue.store.cleanupExpiredMessages();\n```\n\n**With AbortSignal support:**\n\n```ts\nconst controller = new AbortController();\n\n// Consume with cancellation support\n(async () =\u003e {\n  for await (const job of queue.consume(controller.signal)) {\n    await processJob(job);\n    queue.ack(job);\n  }\n})();\n\n// Stop processing after 10 seconds\nsetTimeout(() =\u003e controller.abort(), 10_000);\n```\n\n**With TTL (Time-to-Live) message expiration:**\n\n```ts\nimport { Queue, Message } from \"@jondotsoy/utils-js/queue\";\n\nconst queue = new Queue();\n\n// Add a message that expires in 5 minutes\nconst message = new Message(\n  { task: \"send-notification\", userId: \"123\" },\n  { ttl: 5 * 60 }, // TTL in seconds\n);\nawait queue.add(message);\n\n// Messages are automatically cleaned up when expired\nfor await (const job of queue) {\n  console.log(\"Processing:\", job);\n  queue.ack(job);\n}\n```\n\n**Graceful shutdown:**\n\n```ts\nconst queue = new Queue();\n\n// Start consumers\nconst consumer = (async () =\u003e {\n  for await (const job of queue) {\n    await processJob(job);\n    queue.ack(job);\n  }\n  console.log(\"Consumer stopped gracefully\");\n})();\n\n// Graceful shutdown - completes current messages before stopping\nsetTimeout(() =\u003e queue.close(), 30_000);\nawait consumer;\n\n// Or use Disposable pattern for automatic cleanup\n{\n  using queue = new Queue();\n  // Queue automatically closed when leaving scope\n}\n```\n\n### Queue Options\n\n```ts\nconst queue = new Queue({\n  messageTimeoutMs: 100, // Time before message is considered unacknowledged (default: 100)\n  ackIntervalMs: 100, // Keep-alive acknowledgment interval (default: 100)\n  store: new MemoryStore(), // Custom storage backend (default: new MemoryStore())\n});\n```\n\n### Message Lifecycle \u0026 Acknowledgment\n\nMessages require **explicit acknowledgment** to be deleted from the queue:\n\n```ts\nfor await (const messageData of queue.consume()) {\n  try {\n    await processMessage(messageData);\n\n    // Required: Acknowledge successful processing\n    queue.ack(messageData); // or queue.acknowledgeMessage(messageData)\n  } catch (error) {\n    // Don't acknowledge - message will be reclaimed after timeout\n    console.error(\"Processing failed:\", error);\n  }\n}\n```\n\n**Key behaviors:**\n\n- Messages are only deleted when explicitly acknowledged with `queue.ack()`\n- Unacknowledged messages are automatically reclaimed after `messageTimeoutMs`\n- Keep-alive prevents timeout during long processing\n- Provides at-least-once delivery semantics\n\n### Custom Storage Backend\n\nImplement your own storage by extending the `Store` abstract class:\n\n```ts\nimport { Store, Message } from \"@jondotsoy/utils-js/queue\";\n\nabstract class Store {\n  abstract addMessage(message: Message): Promise\u003cvoid\u003e;\n  abstract getMessage(messageId: string): Promise\u003cMessage | null\u003e;\n  abstract acknowledgeMessage(messageId: string): Promise\u003cvoid\u003e;\n  abstract deleteMessage(messageId: string): Promise\u003cvoid\u003e;\n  abstract claimMessage(\n    acknowledgeTimeoutMs: number,\n    now: number,\n    abort?: AbortSignal,\n  ): Promise\u003cMessage | null\u003e;\n  abstract getSize(): Promise\u003cnumber\u003e;\n  abstract close(): Promise\u003cvoid\u003e;\n}\n\nclass RedisStore extends Store {\n  // Implement Redis-backed storage\n  async addMessage(message: Message): Promise\u003cvoid\u003e {\n    // Your Redis implementation\n  }\n\n  async getMessage(messageId: string): Promise\u003cMessage | null\u003e {\n    // Your Redis implementation\n  }\n\n  async acknowledgeMessage(messageId: string): Promise\u003cvoid\u003e {\n    // Your Redis implementation\n  }\n\n  async deleteMessage(messageId: string): Promise\u003cvoid\u003e {\n    // Your Redis implementation\n  }\n\n  async claimMessage(\n    acknowledgeTimeoutMs: number,\n    now: number,\n  ): Promise\u003cMessage | null\u003e {\n    // Your Redis implementation - should be atomic\n  }\n\n  async getSize(): Promise\u003cnumber\u003e {\n    // Your Redis implementation\n  }\n\n  async close(): Promise\u003cvoid\u003e {\n    // Your Redis cleanup implementation\n  }\n}\n\nconst queue = new Queue({ store: new RedisStore() });\n```\n\n**Built-in stores:**\n\n- **MemoryStore**: Default in-memory storage (development/testing) with automatic TTL cleanup\n- **IndexedDBStore**: Browser-only persistent storage with TTL support - messages survive browser restarts and include automatic cleanup of expired messages\n- **WorkerStore**: Worker-based storage that delegates operations to a Web Worker/Worker Thread - prevents main thread blocking for better performance\n\n### Features\n\n- **🔄 Async Iterator Support**: Clean `for await...of` consumption pattern\n- **🛑 Graceful Shutdown**: `close()` method and Disposable pattern support\n- **💾 Pluggable Storage**: Abstract `Store` interface with in-memory and IndexedDB implementations\n- **⚡ Keep-Alive Acknowledgments**: Prevents message timeout during long processing\n- **⏱️ TTL Support**: Optional Time-to-Live for automatic message expiration and cleanup\n- **🔀 Concurrent Workers**: Multiple consumers safely process different messages\n- **🛡️ Message Recovery**: Automatic reclaim of failed/stalled messages after timeout\n- **✋ Manual Acknowledgment**: Explicit `ack()` required for message deletion\n- **📦 Zero Dependencies**: Pure TypeScript implementation\n- **🔒 Type Safe**: Full TypeScript support with comprehensive type definitions\n- **🔁 At-Least-Once Delivery**: Failed messages are automatically retried\n\n### Use Cases\n\n- **Background job processing**\n- **Task queue coordination between workers**\n- **Event-driven microservices communication**\n- **Batch processing with failure recovery**\n- **Real-time message distribution systems**\n\nFor complete API documentation and advanced usage examples, see [src/queue/README.md](src/queue/README.md).\n\n## Workspace\n\nA powerful and flexible API for executing shell commands in Node.js applications with workspace-centric command execution, environment management, and isolation. Built on top of `@jondotsoy/shell`, it provides managed environments for executing multiple related commands with consistent configuration, automatic timeout handling, and temporary workspace creation. For complete API documentation and advanced usage examples, see [src/workspace/README.md](src/workspace/README.md).\n\n**Syntax:**\n\n```ts\nimport { Workspace } from \"@jondotsoy/utils-js/workspace\";\n// or for both workspace and direct shell access\nimport { shell, Workspace } from \"@jondotsoy/utils-js/workspace\";\n\n// Basic command execution (direct shell)\nconst response = shell(command);\nconst response = shell(command, options);\n\n// Workspace management\nconst workspace = new Workspace(options);\nconst response = workspace.run(command);\nconst response = workspace.run(command, options);\n```\n\n**Arguments:**\n\n- `command` `\u003cstring\u003e`: Command to execute\n- `options` `\u003cobject\u003e`: Optional configuration for shell commands\n  - `stdin` `\u003cReadableStream\u003e`: Input stream to pipe to the command\n  - `env` `\u003cRecord\u003cstring, string\u003e\u003e`: Environment variables\n  - `shell` `\u003cstring\u003e`: Shell to use for execution\n  - `cwd` `\u003cstring\u003e`: Working directory\n  - `signal` `\u003cAbortSignal\u003e`: Signal for cancellation/timeout\n- `options` `\u003cWorkspaceOptions\u003e`: Configuration for workspace\n  - `workingDirectory` `\u003cstring | URL\u003e` **required**: Working directory for the workspace\n  - `shell` `\u003cstring\u003e`: Shell to use for command execution (default: '/bin/sh')\n  - `env` `\u003cRecord\u003cstring, string\u003e\u003e`: Environment variables\n  - `timeout` `\u003cnumber\u003e`: Timeout in milliseconds for all commands in workspace\n\n**Examples:**\n\n```ts\nimport { shell, Workspace } from \"@jondotsoy/utils-js/workspace\";\n\n// Direct shell command execution\nconst response = shell('echo \"Hello World\"');\nconst output = await response.text();\nconsole.log(output); // \"Hello World\"\n\n// Command with timeout\nconst timedResponse = shell(\"long-running-command\", {\n  signal: AbortSignal.timeout(5000), // 5 seconds\n});\n\n// Create a workspace with default settings\nconst workspace = new Workspace({\n  workingDirectory: \"/path/to/project\",\n  shell: \"/bin/bash\",\n  timeout: 30000, // 30 seconds default timeout for all commands\n});\n\n// Execute commands in the workspace context\nconst result1 = workspace.run(\"npm install\");\nconst result2 = workspace.run(\"npm test\");\n\n// All commands inherit workspace configuration\nconst output = await result1.text();\nconst exitCode = await result1.exitCode;\n\n// Temporary workspace\nconst tmpWorkspace = Workspace.mktmp();\nconst response = tmpWorkspace.run('echo \"temp work\" \u003e file.txt');\n\n// Workspace with environment variables\nconst devWorkspace = new Workspace({\n  workingDirectory: \"/project\",\n  env: { NODE_ENV: \"development\", CI: \"true\" },\n});\n\nconst buildResult = devWorkspace.run(\"npm run build\");\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjondotsoy%2Futils-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjondotsoy%2Futils-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjondotsoy%2Futils-js/lists"}