{"id":29225677,"url":"https://github.com/simonepriuli/fx","last_synced_at":"2025-07-03T07:37:45.375Z","repository":{"id":302067920,"uuid":"1011135650","full_name":"simonepriuli/fx","owner":"simonepriuli","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-30T11:06:03.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-30T12:23:25.687Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonepriuli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-06-30T11:02:44.000Z","updated_at":"2025-06-30T11:06:06.000Z","dependencies_parsed_at":"2025-06-30T12:34:43.361Z","dependency_job_id":null,"html_url":"https://github.com/simonepriuli/fx","commit_stats":null,"previous_names":["simonepriuli/fx"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/simonepriuli/fx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonepriuli%2Ffx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonepriuli%2Ffx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonepriuli%2Ffx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonepriuli%2Ffx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonepriuli","download_url":"https://codeload.github.com/simonepriuli/fx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonepriuli%2Ffx/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263284314,"owners_count":23442516,"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","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":[],"created_at":"2025-07-03T07:37:42.588Z","updated_at":"2025-07-03T07:37:45.363Z","avatar_url":"https://github.com/simonepriuli.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fx - Functional Result Type Library\n\nA lightweight, type-safe Result type library for TypeScript that provides a functional approach to error handling.\n\n## Features\n\n- 🎯 **Type-safe error handling** with Result types\n- 🏷️ **Error tagging** for selective error handling\n- ⚡ **Async support** with ResultAsync\n- 🔧 **Functional transformations** (map, flatMap, andThen)\n- 🎲 **Combinators** for working with multiple Results\n- 🛡️ **Safe execution** with tryCatch utilities\n- 📦 **Zero dependencies** - pure TypeScript\n\n## Installation\n\n```bash\nnpm install @fx-ts/fx\n```\n\n## Quick Start\n\n```typescript\nimport { fx } from 'fx';\n\n// Create a function that might fail\nconst divide = fx.fn((a: number, b: number) =\u003e {\n  if (b === 0) {\n    return fx.err(new Error('Division by zero'));\n  }\n  return fx.ok(a / b);\n});\n\n// Use the function\nconst result = divide(10, 2);\n// result: [null, 5] (success)\n\nconst errorResult = divide(10, 0);\n// errorResult: [Error: Division by zero, null] (error)\n\n// Transform results\nconst doubled = fx.map(result, x =\u003e x * 2);\n// doubled: [null, 10]\n\n// Chain operations\nconst chained = fx.andThen(result, x =\u003e {\n  if (x \u003e 3) {\n    return fx.ok(`Big number: ${x}`);\n  }\n  return fx.err(new Error('Number too small'));\n});\n// chained: [null, \"Big number: 5\"]\n```\n\n## Core Concepts\n\n### Result Type\n\nA Result is a tuple `[error, value]` where:\n- `[null, value]` represents success\n- `[error, null]` represents failure\n\n```typescript\ntype Result\u003cR, E\u003e = [null, R] | [E, null];\ntype ResultAsync\u003cR, E\u003e = Promise\u003cResult\u003cR, E\u003e\u003e;\n```\n\n### Creating Results\n\n```typescript\nimport { fx } from 'fx';\n\n// Success\nconst success = fx.ok(42);\n// [null, 42]\n\n// Error\nconst error = fx.err(new Error('Something went wrong'));\n// [Error: Something went wrong, null]\n```\n\n### Safe Function Execution\n\n```typescript\nimport { fx } from 'fx';\n\n// Wrap any function (sync or async)\nconst safeFunction = fx.fn(() =\u003e {\n  // This function might throw\n  const random = Math.random();\n  if (random \u003c 0.5) {\n    throw new Error('Random failure');\n  }\n  return random;\n});\n\nconst result = safeFunction();\n// Always returns a Result, never throws\n```\n\n## API Reference\n\n### Core Functions\n\n#### `fx.ok(value)`\nCreates a success Result.\n\n#### `fx.err(error)`\nCreates an error Result.\n\n#### `fx.fn(function)`\nWraps a function to return Results instead of throwing.\n\n### Transformations\n\n#### `fx.map(result, fn)`\nTransform the success value of a Result.\n\n```typescript\nconst result = fx.ok(5);\nconst doubled = fx.map(result, x =\u003e x * 2);\n// [null, 10]\n```\n\n#### `fx.andThen(result, fn)`\nChain operations on a Result (flatMap).\n\n```typescript\nconst result = fx.ok(5);\nconst chained = fx.andThen(result, x =\u003e {\n  if (x \u003e 3) return fx.ok(x * 2);\n  return fx.err(new Error('Too small'));\n});\n```\n\n#### `fx.mapError(result, fn)`\nTransform the error of a Result.\n\n```typescript\nconst result = fx.err(new Error('Original error'));\nconst transformed = fx.mapError(result, err =\u003e `Custom: ${err.message}`);\n// [\"Custom: Original error\", null]\n```\n\n#### `fx.orElse(result, fn)`\nProvide a fallback when Result is an error.\n\n```typescript\nconst result = fx.err(new Error('Failed'));\nconst fallback = fx.orElse(result, err =\u003e fx.ok('Default value'));\n// [null, \"Default value\"]\n```\n\n### Unwrapping\n\n#### `fx.unwrap(result)`\nExtract the value or throw the error.\n\n```typescript\nconst result = fx.ok(42);\nconst value = fx.unwrap(result); // 42\n\nconst errorResult = fx.err(new Error('Oops'));\nconst value = fx.unwrap(errorResult); // throws Error: Oops\n```\n\n#### `fx.unwrapOr(result, defaultValue)`\nExtract the value or return a default.\n\n```typescript\nconst result = fx.err(new Error('Failed'));\nconst value = fx.unwrapOr(result, 0); // 0\n```\n\n#### `fx.unwrapOrElse(result, fn)`\nExtract the value or compute a default.\n\n```typescript\nconst result = fx.err(new Error('Failed'));\nconst value = fx.unwrapOrElse(result, err =\u003e err.message.length); // 6\n```\n\n### Type Guards\n\n#### `fx.isOk(result)`\nCheck if Result is success.\n\n#### `fx.isErr(result)`\nCheck if Result is error.\n\n### Error Tagging\n\nError tagging allows you to categorize errors and handle them selectively in your pipelines.\n\n#### `fx.tagError(tag, error)`\nCreate a tagged error.\n\n```typescript\nconst taggedError = fx.tagError(\"VALIDATION_ERROR\", \"Invalid input\");\n// { tag: \"VALIDATION_ERROR\", error: \"Invalid input\" }\n```\n\n#### `fx.errTagged(tag, error)`\nCreate a Result with a tagged error.\n\n```typescript\nconst result = fx.errTagged(\"NETWORK_ERROR\", \"Connection failed\");\n// [{ tag: \"NETWORK_ERROR\", error: \"Connection failed\" }, null]\n```\n\n#### `fx.catchByTag(result, tag, handler)`\nCatch errors with a specific tag and handle them.\n\n```typescript\nconst result = fx.errTagged(\"VALIDATION_ERROR\", \"Invalid email\");\n\nconst handled = fx.catchByTag(\n  result,\n  \"VALIDATION_ERROR\",\n  (error) =\u003e fx.ok(`Handled: ${error}`)\n);\n// [null, \"Handled: Invalid email\"]\n```\n\n#### `fx.catchByTags(result, tags, handler)`\nCatch errors with any of the specified tags.\n\n```typescript\nconst result = fx.errTagged(\"NETWORK_ERROR\", \"Connection failed\");\n\nconst handled = fx.catchByTags(\n  result,\n  [\"VALIDATION_ERROR\", \"NETWORK_ERROR\"],\n  (error) =\u003e fx.ok(`Handled: ${error}`)\n);\n// [null, \"Handled: Connection failed\"]\n```\n\n#### `fx.hasTag(error, tag)`\nCheck if an error has a specific tag.\n\n```typescript\nconst taggedError = fx.tagError(\"VALIDATION_ERROR\", \"Invalid input\");\nconst hasTag = fx.hasTag(taggedError, \"VALIDATION_ERROR\"); // true\n```\n\n### Combinators\n\n#### `fx.all(results)`\nCombine multiple Results. Returns success only if all are successful.\n\n```typescript\nconst results = [fx.ok(1), fx.ok(2), fx.ok(3)];\nconst combined = fx.all(results);\n// [null, [1, 2, 3]]\n```\n\n#### `fx.any(results)`\nReturn the first successful Result, or the last error if all fail.\n\n#### `fx.zip(result1, result2)`\nCombine two Results into a tuple.\n\n```typescript\nconst result1 = fx.ok(1);\nconst result2 = fx.ok('hello');\nconst zipped = fx.zip(result1, result2);\n// [null, [1, \"hello\"]]\n```\n\n#### `fx.tryCatch(fn)`\nExecute a function and return a Result.\n\n```typescript\nconst result = fx.tryCatch(() =\u003e {\n  const value = JSON.parse('invalid json');\n  return value;\n});\n// [SyntaxError: Unexpected token i in JSON at position 0, null]\n```\n\n## Async Support\n\nAll functions work with async Results:\n\n```typescript\nimport { fx } from 'fx';\n\nconst asyncResult = fx.fn(async () =\u003e {\n  const response = await fetch('/api/data');\n  if (!response.ok) {\n    return fx.err(new Error('API failed'));\n  }\n  return fx.ok(await response.json());\n});\n\nconst transformed = await fx.mapAsync(asyncResult(), data =\u003e data.name);\n```\n\n## Best Practices\n\n1. **Use Results for expected errors** - Don't use Results for unexpected errors (bugs)\n2. **Chain operations** - Use `fx.andThen` to build complex workflows\n3. **Handle errors explicitly** - Use `fx.mapError` and `fx.orElse` to handle errors gracefully\n4. **Use combinators** - Use `fx.all`, `fx.zip` for working with multiple Results\n5. **Prefer unwrapOr over unwrap** - Avoid throwing in production code\n\n## Examples\n\n### API Call with Error Handling\n\n```typescript\nimport { fx } from 'fx';\n\nconst fetchUser = fx.fn(async (id: number) =\u003e {\n  const response = await fetch(`/api/users/${id}`);\n  if (!response.ok) {\n    return fx.err(new Error(`HTTP ${response.status}`));\n  }\n  return fx.ok(await response.json());\n});\n\nconst getUserName = fx.andThen(fetchUser(123), user =\u003e {\n  if (!user.name) {\n    return fx.err(new Error('User has no name'));\n  }\n  return fx.ok(user.name);\n});\n\nconst result = await getUserName();\n```\n\n### Validation Pipeline\n\n```typescript\nimport { fx } from 'fx';\n\nconst validateEmail = (email: string) =\u003e {\n  if (!email.includes('@')) {\n    return fx.err(new Error('Invalid email'));\n  }\n  return fx.ok(email);\n};\n\nconst validateAge = (age: number) =\u003e {\n  if (age \u003c 18) {\n    return fx.err(new Error('Too young'));\n  }\n  return fx.ok(age);\n};\n\nconst validateUser = (email: string, age: number) =\u003e {\n  const emailResult = validateEmail(email);\n  const ageResult = validateAge(age);\n  \n  return fx.all([emailResult, ageResult]);\n};\n\nconst result = validateUser('user@example.com', 25);\n// [null, [\"user@example.com\", 25]]\n```\n\n### Error Tagging Pipeline\n\n```typescript\nimport { fx } from 'fx';\n\nconst validateInput = (input: string) =\u003e {\n  if (!input) return fx.errTagged(\"VALIDATION_ERROR\", \"Input is required\");\n  if (input.length \u003c 3) return fx.errTagged(\"VALIDATION_ERROR\", \"Input too short\");\n  return fx.ok(input);\n};\n\nconst processData = (input: string) =\u003e {\n  if (input === \"error\") return fx.errTagged(\"PROCESSING_ERROR\", \"Failed to process\");\n  return fx.ok(input.toUpperCase());\n};\n\nconst saveData = (data: string) =\u003e {\n  if (data === \"ERROR\") return fx.errTagged(\"DATABASE_ERROR\", \"Failed to save\");\n  return fx.ok(`Saved: ${data}`);\n};\n\n// Pipeline with selective error handling\nconst pipeline = (input: string) =\u003e {\n  const step1 = validateInput(input);\n  \n  const step2 = fx.catchByTag(\n    step1,\n    \"VALIDATION_ERROR\",\n    (error) =\u003e fx.ok(`Validation failed: ${error}`)\n  );\n  \n  const step3 = processData(fx.unwrap(step2));\n  \n  const step4 = fx.catchByTag(\n    step3,\n    \"PROCESSING_ERROR\",\n    (error) =\u003e fx.ok(`Processing failed: ${error}`)\n  );\n  \n  return saveData(fx.unwrap(step4));\n};\n\nconst result = pipeline(\"hello\");\n// [null, \"Saved: HELLO\"]\n\nconst errorResult = pipeline(\"error\");\n// [null, \"Saved: Processing failed: Failed to process\"]\n```\n\n## License\n\nMIT ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonepriuli%2Ffx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonepriuli%2Ffx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonepriuli%2Ffx/lists"}