{"id":26699713,"url":"https://github.com/santi100a/assertion-lib","last_synced_at":"2025-03-26T23:16:23.027Z","repository":{"id":65816213,"uuid":"575194404","full_name":"santi100a/assertion-lib","owner":"santi100a","description":"Santi's Assertion Library. Official repo for NPM package @santi100a/assertion-lib.","archived":false,"fork":false,"pushed_at":"2023-12-18T18:13:15.000Z","size":626,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-02T12:07:37.248Z","etag":null,"topics":["assertion","es3","lightweight","santi100a","type-assertion","typescript"],"latest_commit_sha":null,"homepage":"https://npmjs.org/package/@santi100a/assertion-lib","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/santi100a.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null},"funding":{"github":"santi100a"}},"created_at":"2022-12-07T00:49:18.000Z","updated_at":"2023-09-23T22:34:03.000Z","dependencies_parsed_at":"2023-02-27T14:45:36.893Z","dependency_job_id":"e5980846-0b72-4f41-b0ba-5fb81e043855","html_url":"https://github.com/santi100a/assertion-lib","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/santi100a%2Fassertion-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/santi100a%2Fassertion-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/santi100a%2Fassertion-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/santi100a%2Fassertion-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/santi100a","download_url":"https://codeload.github.com/santi100a/assertion-lib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245749901,"owners_count":20666086,"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":["assertion","es3","lightweight","santi100a","type-assertion","typescript"],"created_at":"2025-03-26T23:16:22.315Z","updated_at":"2025-03-26T23:16:23.021Z","avatar_url":"https://github.com/santi100a.png","language":"TypeScript","readme":"# Santi's Assertion Library\n\n[![Build Status][build status badge]][actions]\n[![npm homepage][npm homepage badge]][npm homepage]\n[![GitHub stars][gh stars badge]][repo]\n[![License][license badge]][repo]\n[![Bundlephobia stats][bundlephobia badge]][bundlephobia page]\n[![Discord community][discord badge]][discord server]\n\n[license badge]: https://img.shields.io/github/license/santi100a/assertion-lib.svg\n[build status badge]: https://github.com/santi100a/assertion-lib/actions/workflows/ci.yml/badge.svg\n[npm homepage badge]: https://img.shields.io/npm/v/@santi100a/assertion-lib\n[gh stars badge]: https://img.shields.io/github/stars/santi100a/assertion-lib.svg\n[bundlephobia badge]: https://img.shields.io/bundlephobia/min/@santi100a/assertion-lib\n[discord badge]: https://img.shields.io/badge/Join%20us%20on%20Discord-7289DA?logo=discord\u0026logoColor=white\n[actions]: https://github.com/santi100a/assertion-lib/actions\n[npm homepage]: https://npmjs.org/package/@santi100a/assertion-lib\n[repo]: https://github.com/santi100a/assertion-lib\n[bundlephobia page]: https://bundlephobia.com/package/@santi100a/assertion-lib@latest\n[discord server]: https://discord.com/channels/1110705940459696179/1110706009086902303\n\n- 🚀 Lightweight and fast^\n- 👴 ES3-compliant\\*\n- 💻 Portable between the browser and Node.js\n- 📘 Comes with built-in TypeScript definitions\n- 📑 Split into a lot of modules (under `cjs/`) so you get to choose what you want\n- 🎨 Includes a wide array of assertion functions\n- 💪 Very customizable (you get to choose comparison logic, name displayed on error, et cetera)\n\n\\*_Hasn't been tested in an actual ES3 environment. Feel free to open an issue or pull request if you find any non-ES3 thing. See \"Contribute\" for instructions on how to do so._\n\n_^The source code is about 2 kilobytes._\n\n## What's this?\n\nThis is an assertion library for types and conditions. It's designed to be lightweight and portable between\nthe browser and Node.js.\n\n## Contribute\n\nWanna contribute? [File an issue](https://github.com/santi100a/assertion-lib/issues) or [pull request](https://github.com/santi100a/assertion-lib/pulls)!\nMake sure you follow the [contribution Code of Conduct](https://github.com/santi100a/assertion-lib/blob/main/CODE_OF_CONDUCT.md).\n\n## Installation\n\n- Via NPM: `npm install @santi100a/assertion-lib`\n- Via Yarn: `yarn add @santi100a/assertion-lib`\n- Via PNPM: `pnpm install @santi100a/assertion-lib`\n\n### API\n\n- `function assert(condition: boolean, params?: AssertOptionalParams): void;`\n\n  Asserts that `condition` is truthy. Throws an `AssertionError` otherwise.\n\n  | Parameter               | Type                         | Description                               |\n  | ----------------------- | ---------------------------- | ----------------------------------------- |\n  | `condition`             | `boolean`                    | The condition to assert.                  |\n  | `assertParams`          | `AssertOptionalParams\u003cE, A\u003e` | `AssertionError` options.                 |\n  | `assertParams.expected` | `E`                          | Expected value for the assertion.         |\n  | `assertParams.actual`   | `A`                          | Received value for the assertion.         |\n  | `assertParams.operator` | `string`                     | Optional operator used for the assertion. |\n\n- `function assertTypeOf(arg: any, expectedType: Type, name: string): void;` (since 1.0.6, `name` is optional since 1.0.8)\n\n  Asserts that the type of `arg` is `expectedType`. Throws a `TypeError` otherwise.\n  | Parameter | Type | Description |\n  |-------------------------|------------------------------|-------------------------------------------|\n  | `arg` | `any` | An expression whose type is to be asserted. |\n  | `expectedType` | `Type` | The expected type. |\n  | `name` | `string` | An optional expression name to be put in the `TypeError`'s message. Defaults to \"arg\". |\n\n- `function assertOneOf\u003cT = unknown\u003e(arg: any, name: string, choices: any[]): void;` (since 1.0.6, type param bound to `choices` added in 1.0.8)\n\n  Asserts `arg` is one of `choices`, using `comparator` to compare `arg` against each choice.\n  Throws a `TypeError` otherwise.\n\n  **WARNING:**\n  **Since v2, the `shallow` argument is no longer valid -- it has been replaced with `comparator`.**\n\n  This is done so you can use this library without the need to install `@santi100/equal-lib`, whilst also\n  adding flexibility to use custom comparison logic or the deep equality library of your choice.\n\n  | Parameter                   | Type                                           | Description                                                                                      |\n  | --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n  | `arg`                       | `any`                                          | The value that's expected to be included within `choices`.                                       |\n  | `name`                      | `string`                                       | An expression name to be put in the `TypeError`'s message.                                       |\n  | `choices`                   | `T[]`                                          | An array containing the posible values `arg` should have in order for an error not to be thrown. |\n  | `comparator?` (since 2.0.0) | `(a: unknown, b: T) =\u003e boolean` or `undefined` | A custom comparator to add, for instance, deep equality!                                         |\n\n- `function assertInteger(arg: number, name: string): void;` (since 1.0.6)\n\n  Asserts `arg` is an integer. Throws a `TypeError` otherwise.\n\n- `function assertMin(arg: any, name: string, min: any): void;` (since 1.0.6)\n\n  Asserts `arg` is bigger or equal than `min`. Throws a `TypeError` otherwise.\n\n- `function assertMax(arg: any, name: string, max: any): void;` (since 1.0.6)\n\n  Asserts `arg` is smaller or equal than `max`. Throws a `TypeError` otherwise.\n\n- `function assertRange(arg: any, name: string, min: any, max: any): void;` (since 1.0.6)\n\n  Asserts `arg` is **NEITHER** smaller than `min` **NOR** bigger than `max`.\n  Throws a `TypeError` (`RangeError` since 1.0.7) otherwise.\n\n- `function assertArray(arg: any, name?: string): void;` (since 1.0.7)\n\n  Asserts `arg` is an Array. Throws a `TypeError` otherwise.\n\n- `function assertDefined\u003cT = unknown\u003e(element: T): void;` (since 2.0.1)\n\n  Checks if a given element is defined, i.e., not null or undefined.\n  If the element is null or undefined, the function throws a TypeError with a message indicating the name of the element.\n\n  | Parameter | Type | Description                                | Optional? |\n  | --------- | ---- | ------------------------------------------ | --------- |\n  | `element` | `T`  | The value to be checked for being defined. | No        |\n\n  Throws an error if the element is null or undefined.\n\n  Example:\n\n  ```typescript\n  assertDefined(5); // No error thrown\n  assertDefined(null); // Throws TypeError: 'element' is null\n  assertDefined(undefined); // Throws TypeError: 'element' is undefined\n  assertDefined('hello'); // No error thrown\n  ```\n\n- `function assertMatch(str: string, re: RegExp, name?: string): void;` (since 2.0.1)\n\n  Asserts `str` matches `re`. Throws a `TypeError` otherwise.\n\n  | Parameter          | Type     | Description                                                                | Optional? |\n  | ------------------ | -------- | -------------------------------------------------------------------------- | --------- |\n  | `str`              | `string` | The string to match against `re`.                                          | No        |\n  | `re`               | `RegExp` | The regular expression to match `str` against.                             | No        |\n  | `name`             | `string` | The displayed name in the `TypeError` thrown if `str` does not match `re`. |\n  | Defaults to `str`. | No       |\n\n- `function assertArrayTypes\u003cT = unknown\u003e(values: T[], types: Type[]): void;` (since 2.0.3)\n  | Parameter | Type | Description | Optional? |\n  | --------- | ------------ | ---------------------------------------------------------------------------------------------------------------- | --------- |\n  | `values` | `T[]` | An array of elements to be checked. | No |\n  | `types` | `Type[]` | An array of strings representing the expected types of elements in the array. | No |\n\n- `function assertArrayTypes\u003cT = unknown\u003e(values: T[], types: Type[], name: string): void;` (since 2.0.3)\n  | Parameter | Type | Description | Optional? |\n  | --------- | ------------ | ---------------------------------------------------------------------------------------------------------------- | --------- |\n  | `values` | `T[]` | An array of elements to be checked. | No |\n  | `types` | `Type[]` | An array of strings representing the expected types of elements in the array. | No |\n  | `name` | `string` | A string representing the name of the \"values\" array. | No |\n\n## Usage examples\n\n```typescript\n// Import the assertion functions\n\n// CJS\nconst assert = require('@santi100a/assertion-lib/cjs/assert');\nconst assertTypeOf = require('@santi100a/assertion-lib/cjs/type-of');\nconst assertOneOf = require('@santi100a/assertion-lib/cjs/one-of');\nconst assertInteger = require('@santi100a/assertion-lib/cjs/integer');\nconst assertMin = require('@santi100a/assertion-lib/cjs/min');\nconst assertMax = require('@santi100a/assertion-lib/cjs/max');\nconst assertRange = require('@santi100a/assertion-lib/cjs/range');\nconst assertArray = require('@santi100a/assertion-lib/cjs/array');\nconst assertDefined = require('@santi100a/assertion-lib/cjs/defined');\nconst assertMatch = require('@santi100a/assertion-lib/cjs/match');\n\n// TypeScript\nimport assert = require('@santi100a/assertion-lib/cjs/assert');\nimport assertTypeOf = require('@santi100a/assertion-lib/cjs/type-of');\nimport assertOneOf = require('@santi100a/assertion-lib/cjs/one-of');\nimport assertInteger = require('@santi100a/assertion-lib/cjs/integer');\nimport assertMin = require('@santi100a/assertion-lib/cjs/min');\nimport assertMax = require('@santi100a/assertion-lib/cjs/max');\nimport assertRange = require('@santi100a/assertion-lib/cjs/range');\nimport assertArray = require('@santi100a/assertion-lib/cjs/array');\nimport assertDefined = require('@santi100a/assertion-lib/cjs/defined');\nimport assertMatch = require('@santi100a/assertion-lib/cjs/match');\n\n// ESM\nimport assert from '@santi100a/assertion-lib/cjs/assert';\nimport assertTypeOf from '@santi100a/assertion-lib/cjs/type-of';\nimport assertOneOf from '@santi100a/assertion-lib/cjs/one-of';\nimport assertInteger from '@santi100a/assertion-lib/cjs/integer';\nimport assertMin from '@santi100a/assertion-lib/cjs/min';\nimport assertMax from '@santi100a/assertion-lib/cjs/max';\nimport assertRange from '@santi100a/assertion-lib/cjs/range';\nimport assertArray from '@santi100a/assertion-lib/cjs/array';\nimport assertDefined from '@santi100a/assertion-lib/cjs/defined';\nimport assertMatch from '@santi100a/assertion-lib/cjs/match';\n\n// Or import it all\nimport * as assertionLib from '@santi100a/assertion-lib'; // ESM or TypeScript\nconst assertionLib = require('@santi100a/assertion-lib'); // CJS\n// Usage example for assert\nfunction divide(a, b) {\n\tassert(typeof a === 'number' \u0026\u0026 typeof b === 'number', {\n\t\tmessage: 'Arguments must be numbers.'\n\t});\n\n\tassert(b !== 0, {\n\t\tmessage: 'Cannot divide by zero.',\n\t\texpected: 'Non-zero value',\n\t\tactual: b\n\t});\n\n\treturn a / b;\n}\n\n// Usage example for assertTypeOf\nfunction greet(name) {\n\tassertTypeOf(name, 'string', 'name');\n\n\treturn `Hello, ${name}!`;\n}\n\n// Usage example for assertOneOf\nfunction checkOperator(operator) {\n\tassertOneOf(\n\t\toperator,\n\t\t'operator',\n\t\t['+', '-', '*', '/'],\n\t\t(a, b) =\u003e a.trim() === b.trim()\n\t);\n\treturn `Valid operator: ${operator}`;\n}\n\n// Usage example for assertInteger\nfunction multiplyByTwo(num) {\n\tassertInteger(num, 'num');\n\treturn num * 2;\n}\n\n// Usage example for assertMin\nfunction greetWithMinimumLength(name) {\n\tassertMin(name.length, 'name', 3);\n\treturn `Hello, ${name}!`;\n}\n\n// Usage example for assertMax\nfunction greetWithMaximumLength(name) {\n\tassertMax(name.length, 'name', 10);\n\treturn `Hello, ${name}!`;\n}\n\n// Usage example for assertRange\nfunction greetWithPreferredLength(name) {\n\tassertRange(name.length, 'name', 5, 8);\n\treturn `Hello, ${name}!`;\n}\n\n// Usage example for assertArray\nfunction sumNumbers(numbers) {\n\tassertArray(numbers, 'numbers');\n\treturn numbers.reduce((sum, num) =\u003e sum + num, 0);\n}\n\n// Usage example for assertDefined\nfunction greetIfDefined(name) {\n\tassertDefined(name, 'name');\n\treturn `Hello, ${name}!`;\n}\n\n// Usage example for assertMatch\nfunction isValidEmail(email) {\n\tassertMatch(\n\t\temail,\n\t\t/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$/i,\n\t\t'email'\n\t);\n\treturn true;\n}\n```\n","funding_links":["https://github.com/sponsors/santi100a"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanti100a%2Fassertion-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsanti100a%2Fassertion-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanti100a%2Fassertion-lib/lists"}