{"_id":"@ace-riders/js-toolkit","_rev":"3-d0e71f3e10b5ce151eb09284130e1af6","name":"@ace-riders/js-toolkit","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@ace-riders/js-toolkit","version":"0.1.0","author":{"name":"Zdeněk Vítek","email":"zdenek.vitek@asseco-ce.com"},"_id":"@ace-riders/js-toolkit@0.1.0","maintainers":[{"name":"zvitek","email":"zvitek@iwory.cz"}],"git":{"push":false,"commitMessage":":bookmark: ${version} release"},"dist":{"shasum":"0b1499e12f95692c41622b5ee5acd3bba49f6f6d","tarball":"https://registry.npmjs.org/@ace-riders/js-toolkit/-/js-toolkit-0.1.0.tgz","fileCount":14,"integrity":"sha512-+5rNCSGM6sWvYe1BzNJa1rCGDWi19Cg7JBaBQMMZppYoE8Mz4MntgPT3Jbp4XfjFFWeGhU7XJkB9f6W4p9SJ6Q==","signatures":[{"sig":"MEQCIDQ3qZFka83+d7Hij9Xy7oHMT1csI4Ju8IOJkVKpcfiCAiBvbo8pdoNFLlHNRWjpQKNdId1M9LgLlGyopWm6vOPMFg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23289},"type":"module","hooks":{"after:bump":["npm run build-npm && npm publish"],"after:release":"git push origin HEAD"},"gitHead":"fb8bbbe74951afa0c6316dd43cd4efb09a40ce5e","scripts":{"test":"vitest","release":"release-it","test:ui":"vitest --ui","build-npm":"tsc -p ./tsconfig.npm.json"},"_npmUser":{"name":"zvitek","email":"zvitek@iwory.cz"},"repository":{"url":"https://git.asseco-ce.com/zdenek.vitek/ace-riders-js-toolkit.git","type":"git"},"_npmVersion":"11.0.0","description":"This package contains a growing collection of utility functions and helpers designed to streamline development across projects within **Asseco Central Europe**. Its purpose is to consolidate common logic, patterns, and tools that we use repeatedly — to pr","directories":{},"_nodeVersion":"20.19.4","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^7.0.4","jsdom":"^26.1.0","vitest":"^3.2.4","@vitest/ui":"^3.2.4","release-it":"^19.0.4","typescript":"~5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/js-toolkit_0.1.0_1753707819964_0.4346613198303393","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@ace-riders/js-toolkit","version":"0.1.1","author":{"name":"Zdeněk Vítek","email":"zdenek.vitek@asseco-ce.com"},"_id":"@ace-riders/js-toolkit@0.1.1","maintainers":[{"name":"zvitek","email":"zvitek@iwory.cz"}],"dist":{"shasum":"579207001a4459c4956c5f9c916d00225aab0df3","tarball":"https://registry.npmjs.org/@ace-riders/js-toolkit/-/js-toolkit-0.1.1.tgz","fileCount":21,"integrity":"sha512-iGYQA/Cc+jF8qgbggFL8KxdCVCbpFcME95owaiOJklJYJbXcOJQGLq2jY3Sjq/NZMffCfx+tIOc7qyNvqllMHA==","signatures":[{"sig":"MEYCIQDECZNZ/2dTO8IMT7hGuou9+VFEjMa2z3Y96LRnbz2wkAIhAILedbRoo2W13TTjayF2ZpEqgq2VF+82aOfDQz78edw8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26252},"type":"module","gitHead":"eab73696e1376ed0f33e4cf73f94fac1ce099b64","scripts":{"test":"vitest","release":"release-it","test:ui":"vitest --ui","build-npm":"tsc -p ./tsconfig.npm.json"},"_npmUser":{"name":"zvitek","email":"zvitek@iwory.cz"},"release-it":{"git":{"commitMessage":":bookmark: release ${version}"},"npm":{"publish":true},"hooks":{"after:bump":["npm run build-npm && npm publish"],"after:release":"git push origin HEAD"},"github":{"release":false}},"repository":{"url":"https://git.asseco-ce.com/zdenek.vitek/ace-riders-js-toolkit.git","type":"git"},"_npmVersion":"11.0.0","description":"This package contains a growing collection of utility functions and helpers designed to streamline development across projects within **Asseco Central Europe**. Its purpose is to consolidate common logic, patterns, and tools that we use repeatedly — to pr","directories":{},"_nodeVersion":"20.19.4","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^7.0.4","jsdom":"^26.1.0","vitest":"^3.2.4","@vitest/ui":"^3.2.4","release-it":"^19.0.4","typescript":"~5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/js-toolkit_0.1.1_1754395285596_0.9663486825629024","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@ace-riders/js-toolkit","version":"0.1.2","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","author":{"name":"Zdeněk Vítek","email":"zdenek.vitek@asseco-ce.com"},"scripts":{"test":"vitest","test:ui":"vitest --ui","build-npm":"tsc -p ./tsconfig.npm.json","release":"release-it"},"repository":{"type":"git","url":"https://git.asseco-ce.com/zdenek.vitek/ace-riders-js-toolkit.git"},"devDependencies":{"@vitest/ui":"^3.2.4","jsdom":"^26.1.0","release-it":"^19.0.4","typescript":"~5.8.3","vite":"^7.0.4","vitest":"^3.2.4"},"publishConfig":{"access":"public"},"release-it":{"git":{"commitMessage":":bookmark: release ${version}"},"npm":{"publish":true},"github":{"release":false},"hooks":{"after:bump":["npm run build-npm && npm publish"],"after:release":"git push origin HEAD"}},"_id":"@ace-riders/js-toolkit@0.1.2","gitHead":"eab73696e1376ed0f33e4cf73f94fac1ce099b64","description":"This package contains a growing collection of utility functions and helpers designed to streamline development across projects within **Asseco Central Europe**. Its purpose is to consolidate common logic, patterns, and tools that we use repeatedly — to pr","_nodeVersion":"20.19.4","_npmVersion":"11.0.0","dist":{"integrity":"sha512-LidBhE00pqSvVew/YZkb2jAILdSTRFg21SCJLyMGOZAxZk7IjlIjURCFIY/thEAoBt9qeBWQBOPFBEc2eywNlw==","shasum":"93ca2508d095df27b090a6866f5172a676b1d44c","tarball":"https://registry.npmjs.org/@ace-riders/js-toolkit/-/js-toolkit-0.1.2.tgz","fileCount":21,"unpackedSize":26350,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCrZ5HUIxDDtZkyAarHR0aN0Knf95dUxcY2rZrXNE9JfQIgAZ/oXAoITE2lFqg4GQUGiD/0C9hIOnftz5DDwJL+d0E="}]},"_npmUser":{"name":"zvitek","email":"zvitek@iwory.cz"},"directories":{},"maintainers":[{"name":"zvitek","email":"zvitek@iwory.cz"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/js-toolkit_0.1.2_1754395574541_0.6955611446684153"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-28T13:03:39.898Z","modified":"2025-08-05T12:06:14.947Z","0.1.0":"2025-07-28T13:03:40.160Z","0.1.1":"2025-08-05T12:01:25.754Z","0.1.2":"2025-08-05T12:06:14.743Z"},"author":{"name":"Zdeněk Vítek","email":"zdenek.vitek@asseco-ce.com"},"repository":{"type":"git","url":"https://git.asseco-ce.com/zdenek.vitek/ace-riders-js-toolkit.git"},"description":"This package contains a growing collection of utility functions and helpers designed to streamline development across projects within **Asseco Central Europe**. Its purpose is to consolidate common logic, patterns, and tools that we use repeatedly — to pr","maintainers":[{"name":"zvitek","email":"zvitek@iwory.cz"}],"readme":"# 🧰 Asseco Utilities Toolkit\n\nThis package contains a growing collection of utility functions and helpers designed to streamline development across projects within **Asseco Central Europe**. Its purpose is to consolidate common logic, patterns, and tools that we use repeatedly — to promote consistency, reduce duplication, and speed up delivery.\n\nWhether it's a data transformation, safe type guards, object utilities, or runtime helpers, this toolkit is maintained with internal use in mind — but is built to be modular and extensible.\n\n**Contributions are welcome**!  \nIf you have suggestions, bugfixes, or want to integrate new features, feel free to open a pull request or reach out directly.\n\n## Helpers\n\n### 🧩 has\nA lightweight, type-safe helper to check whether an object contains a given property — with proper TypeScript narrowing.\n\nUnlike using `prop in obj`, this approach retains value type safety and supports type guards, allowing downstream code to safely access the property.\n\n#### 🧠 Why use has()?\n- Avoids pitfalls of in operator and optional chaining when type safety matters\n- Ensures that TypeScript narrows the type after the check\n- Uses `Object.prototype.hasOwnProperty.call` internally, which is the safest approach *(even for objects with shadowed or missing hasOwnProperty)*\n\n#### 📦 Example\n\n```typescript\ntype User = {\n  id: number;\n  name?: string;\n}\n\nconst data: unknown = { id: 42 };\n\nif (has<\"id\", number, typeof data>(\"id\", data)) {\n  // `data` is now narrowed to: { id: number }\n  console.log(data.id); // ✅ Safe access\n}\n```\n\nYou can optionally omit the type parameters when inference is enough:\n\n```typescript\nif (has(\"name\", user)) {\n  console.log(user.name.toUpperCase()); // ✅ No \"possibly undefined\" warning\n}\n```\n\n#### 🛠 Use Cases\n\n- Runtime property checks while retaining static type guarantees\n- Safe handling of dynamic objects or external data (e.g. from APIs)\n- Type refinement in utility functions, guards, or transforms\n\n---\n\n### 🧩 is\nThe `is()` function is a narrowing type guard that filters out undefined and null, helping you ensure that a value is defined and non-null.\n\nThis is especially useful when working with optional values, functional filtering, or mapping operations where TypeScript loses precision.\n\n#### 📦 Example\n\n```typescript\nconst maybeName: string | undefined | null = getName();\n\nif (is(maybeName)) {\n  // maybeName is now type string\n  console.log(maybeName.toUpperCase());\n}\n```\n\n#### 🛠 Use Cases\n- Filtering arrays with optional or nullable items\n- Safe navigation with optional chaining results\n- Transforming nullable data\n\n---\n\n### 🧩 isObject\n\nThe `isObject()` function checks whether a given value is of type \"object\" — helping distinguish objects from primitives in a type-safe way.\n\nThis is especially useful when working with unknown or external data (e.g., from APIs or untyped inputs), where you need to guard before accessing properties.\n\n#### 📦 Example\n\n```typescript\nconst maybe = JSON.parse(data);\n\nif (isObject(maybe)) {\n  // Safe to access properties\n  console.log(maybe[\"id\"]);\n}\n```\n\n#### ⚠️ Important Notes\nThis function does not exclude `null`, which is also of type \"object\" in JavaScript. In this case, you can use `isSafeObject` function.\n\n#### 🛠 Use Cases\n- Validating dynamic data\n- Type guards before deep access\n- Parsing JSON or query strings\n\n---\n\n### 🧩 isString\nThe `isString()` function is a type guard that checks whether a given value is a non-null, non-undefined string.\n\nIt builds upon the `is()` helper to safely handle unknown or nullable inputs, and ensures strict type narrowing to string.\n\n#### 📦 Example\n\n```typescript\nconst input: unknown = \"Hello\";\n\nif (isString(input)) {\n  // input is now typed as string\n  console.log(input.toUpperCase());\n}\n```\n\n#### 🛠 Use Cases\n- Validating external input\n- Filtering mixed arrays\n- Guarding before string-specific logic\n\n---\n\n### 🧩 isNumber\n\nThe `isNumber()` function is a type guard that checks whether a given value is a defined, non-null number.\n\nIt extends the `is()` helper and ensures safe type narrowing, especially useful when working with dynamic or unknown inputs.\n\n#### 📦 Example\n```typescript\nconst value = form.get(\"age\");\nif (isNumber(value)) {\n  console.log(\"Age in months:\", value * 12);\n}\n```\n\n### 🛠 Use Cases\n- Validating numeric input\n- Filtering data arrays\n- Enforcing numeric logic\n\n---\n\n### 🧩 omit\n\nThe `omit()` function creates a shallow copy of an object excluding a specified list of keys.\n\nThis is the counterpart to `pick()` and is useful when you want to keep “everything else” except certain properties.\n\n#### 📦 Example\n\n```typescript\nconst user = {\n  id: 1,\n  name: \"Alice\",\n  password: \"secret\",\n  email: \"alice@example.com\",\n};\n\nconst safeUser = omit(user, [\"password\"]);\n// => { id: 1, name: \"Alice\", email: \"alice@example.com\" }\n\ntype SafeUser = typeof safeUser;\n// type SafeUser = { id: number; name: string; email: string }\n```\n\n#### 🛠 Use Cases\n- Removing sensitive data\n- UI state shaping\n- Cleaning API payloads\n- Composing objects dynamically\n- Selective serialization\n\n---\n\n### 🧩 pick\nThe `pick()` function allows you to create a shallow copy of an object containing only a specified subset of its keys.\n\nIt’s a type-safe way to extract relevant properties from a larger object, commonly used in data transformation, serialization, or sanitization layers.\n\n#### 📦 Example\n\n```typescript\nconst user = {\n  id: 1,\n  name: \"Alice\",\n  email: \"alice@example.com\",\n  role: \"admin\"\n}\n\nconst publicData = pick(user, [\"id\", \"name\"]);\n// => { id: 1, name: \"Alice\" }\n\ntype PublicUser = typeof publicData;\n// type PublicUser = { id: number; name: string }\n```\n\n#### 🛠 Use Cases\n- Select only relevant data to expose *(e.g., from user object)*\n- Prepare objects for transmission or logging\n- Normalize partial data in reducers or state transformations\n\n#### ⚠️ Notes\n- This implementation is **shallow** — it is not deep clone values.\n- It uses `Object.entries()` internally, which skips inherited properties *(safe for plain objects)*.\n- The as `Pick<T, K>` cast ensures proper typing even with runtime filtering.\n\n---\n\n### 🧩 property\nThe `property()` helper is a safe property accessor that attempts to retrieve a value by key, returning undefined if the property does not exist — with type safety.\n\nIt builds upon the has() function to avoid potential runtime errors when working with unknown or dynamic objects while preserving TypeScript’s inference.\n\n#### 📦 Example\n\n```typescript\nconst user = {\n  id: 1,\n  name: \"Alice\",\n  age: 30,\n}\n\nconst age = property(\"age\", user);\n// => 30\n\nconst role = property(\"role\", user);\n// => undefined\n```\nBecause the check uses `has()`, the function respects actual object ownership and avoids inherited or prototype properties.\n\n#### 🛠 Use Cases\n- Safe access without optional chaining\n- Dynamic property lookups\n- Graceful fallbacks\n- Combine with has() for manual guards\n\n---\n\n### 🧩 tryDo / tryDoAsync\nA lightweight utility to handle success and error states in a type-safe and consistent way, inspired by the Result type in languages like Rust.\n\nThese helpers provide a unified approach to managing operations that may fail while avoiding exceptions and promoting explicit handling of errors.\n\n#### ✅ Features\n- Strongly typed `Result<T, E>` structure\n- Helper functions `ok()` and `err()` for creating results\n- Synchronous `tryDo()` wrapper\n- Asynchronous `tryDoAsync()` wrapper\n- Compatible with any `Error` subtype\n\n#### 💡 Example\n\nSafely executes a synchronous function and returns a `Result`.\n\n```javascript\nconst result = tryDo(() => JSON.parse(\"not json\"));\n\nif (result.ok) {\n    console.log(\"Success:\", result.value);\n} else {\n    console.error(\"Parsing failed:\", result.error.message);\n}\n```\n\nSafely executes an asynchronous function and returns a `Promise<Result>`.\n\n```javascript\nconst result = await tryDoAsync(() => fetch(\"/api/data\").then(res => res.json()));\n\nif (result.ok) {\n    console.log(\"Data:\", result.value);\n} else {\n    console.error(\"API call failed:\", result.error.message);\n}\n```\n\n#### 📦 Use Cases\n- Replace try/catch blocks with a functional API\n- Normalize error handling across sync/async logic\n- Improve clarity in services, utilities, or data fetchers\n\n\n## Utility Types\n\nA set of common type utilities that help improve expressiveness and type safety across TypeScript codebases.\n\n### 🔹 Optional<T>\n\nRepresents a value that may or may not be defined. Useful for optional function parameters, config fields, or partial values.\n\n### 🔹 Nullable<T>\n\nRepresents a value that can explicitly be `null`. Useful when modeling values from external APIs or legacy systems that use null as a placeholder.\n\n### 🔹 OptionalProperty<T, K>\n\nMakes only a subset of properties (K) optional in a given type T. Useful for selectively loosening type requirements, e.g. in partial form updates or patch requests.\n\n#### Example\n\n```typescript\ntype User = { id: string; name: string; age: number }\ntype PartialName = OptionalProperty<User, \"name\">\n// => { name?: string; id: string; age: number }\n```\n\n### 🔹 ValueOf<T>\n\nExtracts a union of all value types in an object type T. Useful for working with enums, maps, or records.\n\n#### Example\n\n```typescript\ntype Colors = { primary: \"red\"; secondary: \"blue\" }\ntype ColorValues = ValueOf<Colors>\n// => \"red\" | \"blue\"\n```\n\n","readmeFilename":"README.md"}