{"id":20791466,"url":"https://github.com/meistrari/resguard","last_synced_at":"2025-05-05T21:22:21.599Z","repository":{"id":167234159,"uuid":"642627295","full_name":"meistrari/resguard","owner":"meistrari","description":"🛡 Typescript promise result guarding library","archived":false,"fork":false,"pushed_at":"2023-06-23T13:48:19.000Z","size":164,"stargazers_count":58,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-03T00:37:59.042Z","etag":null,"topics":["guard","promise","typescript"],"latest_commit_sha":null,"homepage":"","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/meistrari.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2023-05-19T02:03:01.000Z","updated_at":"2024-11-13T16:02:02.000Z","dependencies_parsed_at":"2023-07-11T19:01:07.698Z","dependency_job_id":null,"html_url":"https://github.com/meistrari/resguard","commit_stats":null,"previous_names":["henrycunh/resguard","meistrari/resguard"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meistrari%2Fresguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meistrari%2Fresguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meistrari%2Fresguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meistrari%2Fresguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meistrari","download_url":"https://codeload.github.com/meistrari/resguard/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252577171,"owners_count":21770745,"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":["guard","promise","typescript"],"created_at":"2024-11-17T15:44:47.025Z","updated_at":"2025-05-05T21:22:21.549Z","avatar_url":"https://github.com/meistrari.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=center\u003e\n\n# 🛡️ resguard\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![Codecov][codecov-src]][codecov-href]\n\n\u003c/div\u003e\n\n`resguard` is a tiny utility that wraps promises and returns an object or tuple with `data` and `error` properties. It's useful for handling errors in async functions without having to use `try/catch` blocks.\n\n## highlights\n\n- 🛡 Wraps promises and returns an object or tuple with data and error properties\n- 🎯 TypeScript support with type checking\n- 🛠️ Custom error handling support\n- ⚡ Minimal dependencies and small bundle size\n\n## usage\n\n```bash\nnpm install resguard\n```\n\n```typescript\nimport { resguard } from 'resguard'\n\nasync function fetchData() {\n    const client = new APIClient()\n\n    const { data, error } = await resguard(client.getItems())\n    if (error) \n        handle(error)\n    \n    const updated = await resguard(client.updateItems(data))\n    if (updated.error) \n        handle(updated.error)\n\n    return updated.data\n}\n```\n\u003csup\u003e\u003cstrong\u003eBoth the `data` and `error` properties of the result are correctly typed\u003c/strong\u003e\u003c/sup\u003e\n\n\n```typescript\nimport { resguard } from 'resguard'\n\nconst result = resguard(() =\u003e {\n    if (Math.random() \u003e 0.5) \n        return true\n    else \n        throw new Error('Something went wrong')\n})\n\nif (result.error) \n    handle(result.error)\n```\n\u003csup\u003e\u003cstrong\u003e`resguard` can also be used with functions. When they are sync, the result also is!\u003c/strong\u003e\u003c/sup\u003e\n\n```typescript\nimport { resguard } from 'resguard'\n\nconst result = await resguard(async () =\u003e {\n    const client = new APIClient()\n    const items = await client.getItems()\n    return items.map(item =\u003e item.id)\n})\n\nif (result.error) \n    handle(result.error)\n```\n\u003csup\u003e\u003cstrong\u003e`resguard` can also be used with async functions.\u003c/strong\u003e\u003c/sup\u003e\n\n```typescript\nimport { resguardFn } from 'resguard'\n\nconst safeJSONParse = resguardFn(JSON.parse)\n\nlet result = safeJSONParse('{ \"test\": 1 }')\nconsole.log(result.data) // { test: 1 }\n\nresult = safeJSONParse('{ missing the other one')\nconsole.log(result.error) // SyntaxError: Unexpected character 'm' (1:2)\n```\n\u003csup\u003e\u003cstrong\u003e`resguardFn` is a wrapper around `resguard` that takes a function as an argument and returns a function that can be called with the same arguments, but guarded.\u003c/strong\u003e\u003c/sup\u003e\n\u003ctable \u003e\n\u003ctr\u003e\n\u003cth\u003e\u003cp\u003e\u003cstrong\u003e❌ depressing\u003c/strong\u003e\u003c/p\u003e\u003c/th\u003e\n\u003cth\u003e\u003cp\u003e\u003cstrong\u003e✅ awesome\u003c/strong\u003e\u003c/p\u003e\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```typescript\nlet result\n\ntry {\n    result = await client.getItems()\n} catch (error) {\n    handle(error)\n}\n```\n\u003c/td\u003e\n\u003ctd\u003e\n\n```typescript\nconst result = await resguard(client.getItems())\nif (result.error) \n    handle(result.error)\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```typescript\nlet result\n\ntry {\n    result = await client.longRequest()\n} catch (e: any) {\n    const error: ClientError = e\n    if (error.code === 'TIMEOUT')\n      handleTimeout()\n}\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```typescript\nconst result = await resguard(client.longRequest(), ClientError)\nif (result.error) {\n    if (error.code === 'TIMEOUT')\n      handleTimeout()\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd\u003e\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```typescript\nlet result\ntry {\n  result = JSON.parse(data)\n} catch (e: any) {\n  const error: SyntaxError = e\n  handle(error)\n}\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```typescript\nconst result = resguard(() =\u003e JSON.parse(data), SyntaxError)\nif (result.error) \n    handle(result.error)\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd\u003e\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```typescript\nlet data: { test: number }\n\ntry {\n  data = JSON.parse('{ test: 1 }')\n} catch (e: any) {\n  const error: SyntaxError = e\n  handle(error)\n}\n\nconsole.log(data.test)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```typescript\nconst { data, error } = resguard\u003c{ test: number}\u003e(\n    () =\u003e JSON.parse('{ test: 1 }'), \n    SyntaxError\n)\n\nif (error) \n    handle(error)\n\nconsole.log(data.test)\n```\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd\u003e\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```typescript\nasync function complexFunction() {\n  let items\n  try {\n    items = await client.getItems()\n  } catch (e: any) {\n    const error: ClientError = e\n    handle(error)\n  }\n\n  let updated\n  try {\n    updated = await client.updateItems(items)\n  } catch (e: any) {\n    const error: ClientError = e\n    handle(error)\n  }\n\n  return updated\n}\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```typescript\nasync function complexFunction() {\n  const items = await resguard(client.getItems(), ClientError)\n  if (items.error) \n    handle(items.error)\n\n  const updatedItems = await resguard(client.updateItems(items), ClientError)\n  if (updatedItems.error) \n    handle(updatedItems.error)\n\n  return updatedItems.data\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c/table\u003e\n\n\n## using tuples\n\nresguard can also return a tuple with data and error values:\n\n```javascript\nimport { resguard } from 'resguard';\n\nasync function fetchData() {\n  const service = new DataService();\n  const [[data, error]] = await resguard(service.getItems());\n\n  if (error) {\n    console.error(\"Error:\", error);\n    return;\n  }\n\n  return data;\n}\n```\n\n## custom error handling\n\nresguard supports custom error handling by allowing you to override the error type:\n\n```javascript\nimport { resguard } from 'resguard';\n\nclass CustomError extends Error {}\n\nasync function fetchData() {\n  const service = new DataService();\n  const [[data, error]] = await resguard(() =\u003e throw new CustomError('damn!'), CustomError);\n\n  if (error) {\n    console.error(\"Custom Error:\", error);\n    console.log(error instanceof CustomError) // true\n    return;\n  }\n\n  return data;\n}\n```\n\n\n[npm-version-src]: https://img.shields.io/npm/v/resguard?style=flat\u0026colorA=18181B\u0026colorB=F0DB4F\n[npm-version-href]: https://npmjs.com/package/resguard\n[npm-downloads-src]: https://img.shields.io/npm/dm/resguard?style=flat\u0026colorA=18181B\u0026colorB=F0DB4F\n[npm-downloads-href]: https://npmjs.com/package/resguard\n[codecov-src]: https://img.shields.io/codecov/c/gh/henrycunh/resguard/main?style=flat\u0026colorA=18181B\u0026colorB=F0DB4F\n[codecov-href]: https://codecov.io/gh/henrycunh/resguard","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeistrari%2Fresguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeistrari%2Fresguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeistrari%2Fresguard/lists"}