{"id":26956291,"url":"https://github.com/m1kc3b/explicitly","last_synced_at":"2025-04-03T03:21:10.348Z","repository":{"id":285725516,"uuid":"959105938","full_name":"m1kc3b/explicitly","owner":"m1kc3b","description":"A TypeScript library inspired by Rust’s Option\u003cT\u003e and Result\u003cT, E\u003e, providing safe and expressive error handling. Avoid null, undefined, and exceptions with explicit, functional-style handling of missing values and errors. 🚀","archived":false,"fork":false,"pushed_at":"2025-04-02T10:00:42.000Z","size":4,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-02T11:21:33.563Z","etag":null,"topics":["error-handling","functional-programming","monad","no-exception","safe-types","typescript"],"latest_commit_sha":null,"homepage":"","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/m1kc3b.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}},"created_at":"2025-04-02T09:22:41.000Z","updated_at":"2025-04-02T10:07:39.000Z","dependencies_parsed_at":"2025-04-02T11:21:37.482Z","dependency_job_id":"ebebcef1-cfb4-4f26-8c99-9dc6ace97315","html_url":"https://github.com/m1kc3b/explicitly","commit_stats":null,"previous_names":["m1kc3b/explicit-error"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m1kc3b%2Fexplicitly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m1kc3b%2Fexplicitly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m1kc3b%2Fexplicitly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m1kc3b%2Fexplicitly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m1kc3b","download_url":"https://codeload.github.com/m1kc3b/explicitly/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246928414,"owners_count":20856286,"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":["error-handling","functional-programming","monad","no-exception","safe-types","typescript"],"created_at":"2025-04-03T03:21:09.847Z","updated_at":"2025-04-03T03:21:10.314Z","avatar_url":"https://github.com/m1kc3b.png","language":"TypeScript","readme":"# Explicitly\n\n`Explicitly` is a TypeScript library inspired by Rust that introduces Option\u003cT\u003e and Result\u003cT, E\u003e. These types eliminate null, undefined, and unexpected exceptions by enforcing explicit handling of missing values and errors. With a functional approach, explicit enhances code robustness and readability while offering intuitive methods such as unwrapOr(), map(), and isOk().\n\nWhether you're dealing with uncertain data, handling API errors, or preventing crashes due to missing values, `Explicitly` provides a safe and elegant alternative to traditional error-handling practices in JavaScript and TypeScript.\n\nThis library implements two generic types:\n- Option\\\u003cT\u003e: stands for a real that can exist (Some\\\u003cT\u003e) or be absent (None).\n- Result\u003cT, E\u003e: stands for either a successful value (Ok\\\u003cT\u003e) or an error (Err\\\u003cE\u003e).\n\n## `Option\u003cT\u003e`\n\nIt is a safer alternative to null (the billion-dollar mistake) and undefined.\n\nNone, represents the absence of a value and forces the developer to handle this case explicitly.\n\nSome\\\u003cT\u003e contains a value and provides method to handle it.\n\n\n## `Result\u003cT, E\u003e`\n\nIt is an alternative to `throw new Error()` and involve to handle errors explicitly.\n\nOk\\\u003cT\u003e contains a successfull value, and provides methods to handle it.\n\nErr\\\u003cE\u003e contains an error and prevents use without verification.\n\n\u003c!-- \n```\ntype User = { id: number; name: string };\n\nfunction findUserById(id: number): Option\u003cUser\u003e {\n  const users: User[] = [{ id: 1, name: \"Alice\" }];\n  const user = users.find(u =\u003e u.id === id);\n  return user ? some(user) : none();\n}\n\nconst user = findUserById(2);\nconsole.log(user.unwrapOr({ id: 0, name: \"Invité\" })); // { id: 0, name: \"Invité\" }\n\n```\n## Examples\n\n### 1 - Retrieving a value from an object (without undefined)\n\nProblem: We are accessing the property of an object that may not exist.\n\n```\ntype User = { id: number; name?: string };\n\nfunction getUserName(user: User): Option\u003cstring\u003e {\n  return user.name ? some(user.name) : none();\n}\n\nconst user: User = { id: 1 };\nconst userName = getUserName(user).unwrapOr(\"Anonyme\");\n\nconsole.log(userName); // \"Anonyme\"\n\n```\nBenefits:\n- Avoids accessing undefined.\n- Allows you to provide a default value with unwrapOr().\n\n### 2 - Database Search (without null)\n\nProblem: A query may not return any results.\n\n```\ntype User = { id: number; name: string };\n\nfunction findUserById(id: number): Option\u003cUser\u003e {\n  const users: User[] = [{ id: 1, name: \"Alice\" }];\n  const user = users.find(u =\u003e u.id === id);\n  return user ? some(user) : none();\n}\n\nconst user = findUserById(2);\nconsole.log(user.unwrapOr({ id: 0, name: \"Invité\" })); // { id: 0, name: \"Invité\" }\n\n```\nBenefits:\n- Force to handle the case where the user is not found.\n\n### 3 - Securely extracting values ​​from an HTML form\n\nIssue: A field may be missing or empty.\n\n```\nfunction getInputValue(id: string): Option\u003cstring\u003e {\n  const input = document.getElementById(id) as HTMLInputElement | null;\n  return input?.value ? some(input.value) : none();\n}\n\nconst email = getInputValue(\"email\").unwrapOr(\"default@example.com\");\nconsole.log(email);\n\n```\nBenefits:\n- Avoids returning null if the element doesn't exist.\n- Allows you to provide a default value properly.\n\n### 4 - Safe division (avoid errors)\n\nProblem: Division by zero can crash the program.\n\n```\nfunction safeDivide(a: number, b: number): Result\u003cnumber, string\u003e {\n  if (b === 0) return err(\"Division by zero\");\n  return ok(a / b);\n}\n\nconst result = safeDivide(10, 0);\nconsole.log(result.unwrapOr(-1)); // -1 au lieu d'une erreur\n\n```\nBenefits:\n- Avoids the use of try/catch.\n- Forces explicit error handling.\n\n### 5 - Reading Files in Node.js\n\nProblem: A file may not exist.\n\n```\nimport fs from \"fs\";\n\nfunction readFileContent(path: string): Result\u003cstring, string\u003e {\n  try {\n    return ok(fs.readFileSync(path, \"utf8\"));\n  } catch {\n    return err(\"File not found\");\n  }\n}\n\nconst fileContent = readFileContent(\"config.json\").unwrapOr(\"{}\");\nconsole.log(fileContent);\n\n```\nBenefits:\n- Avoids the need to use try/catch.\n- Allows clean error handling with unwrapOr().\n\n### 6 - REST API: Proper HTTP Error Handling\n\nIssue: An API request may fail.\n\n```\nasync function fetchUser(id: number): Promise\u003cResult\u003c{ id: number; name: string }, string\u003e\u003e {\n  try {\n    const res = await fetch(`https://api.example.com/users/${id}`);\n    if (!res.ok) return err(`HTTP error ${res.status}`);\n    return ok(await res.json());\n  } catch {\n    return err(\"Network error\");\n  }\n}\n\nfetchUser(1).then(result =\u003e {\n  if (result.isOk()) console.log(result.unwrap());\n  else console.error(\"Error:\", result.unwrapOr({ id: 0, name: \"Error\" }));\n});\n\n```\nBenefits:\n- Avoids having to manage try/catch in the caller.\n- Allows you to return a default value in case of failure.\n\n## How to use it\n\n`$ npm install explicitly`\n\n```\nimport { some, none, Option, ok, err, Result } from \"explicitly\";\n\nconst maybeValue: Option\u003cstring\u003e = some(\"Hello\");\nconsole.log(maybeValue.unwrapOr(\"Default\"));\n\nconst result: Result\u003cnumber, string\u003e = ok(42);\nconsole.log(result.isOk() ? result.unwrap() : \"Error\");\n\n``` --\u003e","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm1kc3b%2Fexplicitly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm1kc3b%2Fexplicitly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm1kc3b%2Fexplicitly/lists"}