feat(utils): create new utils package

README.md

@@ -233,6 +233,28 @@ The core of the Semaphore protocol is in the [circuit logic](/packages/circuits/
                 </a>
             </td>
         </tr>
+        <tr>
+            <td>
+                <a href="/packages/utils">
+                    @semaphore-protocol/utils
+                </a>
+                <a href="https://js.semaphore.pse.dev/modules/_semaphore_protocol_utils">
+                    (docs)
+                </a>
+            </td>
+            <td>
+                <!-- NPM version -->
+                <a href="https://npmjs.org/package/@semaphore-protocol/utils">
+                    <img src="https://img.shields.io/npm/v/@semaphore-protocol/utils.svg?style=flat-square" alt="NPM version" />
+                </a>
+            </td>
+            <td>
+                <!-- Downloads -->
+                <a href="https://npmjs.org/package/@semaphore-protocol/utils">
+                    <img src="https://img.shields.io/npm/dm/@semaphore-protocol/utils.svg?style=flat-square" alt="Downloads" />
+                </a>
+            </td>
+        </tr>
         <tr>
             <td>
                 <a href="/packages/heyauthn">

packages/utils/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ethereum Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/utils/README.md

@@ -0,0 +1,80 @@
+<p align="center">
+    <h1 align="center">
+        Semaphore utils
+    </h1>
+    <p align="center">A library to provide utility functions to the other Semaphore packages.</p>
+</p>
+
+<p align="center">
+    <a href="https://github.com/semaphore-protocol">
+        <img src="https://img.shields.io/badge/project-Semaphore-blue.svg?style=flat-square">
+    </a>
+    <a href="https://github.com/semaphore-protocol/semaphore/blob/main/LICENSE">
+        <img alt="NPM license" src="https://img.shields.io/npm/l/%40semaphore-protocol%2Futils?style=flat-square">
+    </a>
+    <a href="https://www.npmjs.com/package/@semaphore-protocol/utils">
+        <img alt="NPM version" src="https://img.shields.io/npm/v/@semaphore-protocol/utils?style=flat-square" />
+    </a>
+    <a href="https://npmjs.org/package/@semaphore-protocol/utils">
+        <img alt="Downloads" src="https://img.shields.io/npm/dm/@semaphore-protocol/utils.svg?style=flat-square" />
+    </a>
+    <a href="https://js.semaphore.pse.dev/utils">
+        <img alt="Documentation typedoc" src="https://img.shields.io/badge/docs-typedoc-744C7C?style=flat-square">
+    </a>
+    <a href="https://eslint.org/">
+        <img alt="Linter eslint" src="https://img.shields.io/badge/linter-eslint-8080f2?style=flat-square&logo=eslint" />
+    </a>
+    <a href="https://prettier.io/">
+        <img alt="Code style prettier" src="https://img.shields.io/badge/code%20style-prettier-f8bc45?style=flat-square&logo=prettier" />
+    </a>
+</p>
+
+<div align="center">
+    <h4>
+        <a href="https://github.com/semaphore-protocol/semaphore/blob/main/CONTRIBUTING.md">
+            👥 Contributing
+        </a>
+        <span>&nbsp;&nbsp;|&nbsp;&nbsp;</span>
+        <a href="https://github.com/semaphore-protocol/semaphore/blob/main/CODE_OF_CONDUCT.md">
+            🤝 Code of conduct
+        </a>
+        <span>&nbsp;&nbsp;|&nbsp;&nbsp;</span>
+        <a href="https://github.com/semaphore-protocol/semaphore/contribute">
+            🔎 Issues
+        </a>
+        <span>&nbsp;&nbsp;|&nbsp;&nbsp;</span>
+        <a href="https://semaphore.pse.dev/discord">
+            🗣️ Chat &amp; Support
+        </a>
+    </h4>
+</div>
+
+> [!NOTE]  
+> Please, for more information on the modules provided by this library, see its code documentation [here](https://js.semaphore.pse.dev/modules/_semaphore_protocol_utils).
+
+## 🛠 Install
+
+### npm or yarn
+
+Install the `@semaphore-protocol/utils` package with npm:
+
+```bash
+npm i @semaphore-protocol/utils
+```
+
+or yarn:
+
+```bash
+yarn add @semaphore-protocol/utils
+```
+
+## 📜 Usage
+
+```typescript
+// You can import modules from the main bundle.
+import { errors, types } from "@semaphore-protocol/utils"
+
+// Or by using conditional exports.
+import { requireNumber } from "@semaphore-protocol/utils/errors"
+import { isNumber } from "@semaphore-protocol/utils/types"
+```

packages/utils/build.tsconfig.json

@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "baseUrl": ".",
+        "declarationDir": "dist/types"
+    },
+    "include": ["src"]
+}

packages/utils/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@semaphore-protocol/utils",
+    "version": "4.0.0-alpha.8",
+    "description": "A library to provide utility functions to the other Semaphore packages.",
+    "type": "module",
+    "license": "MIT",
+    "main": "dist/index.js",
+    "types": "dist/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/types/index.d.ts",
+            "require": "./dist/index.cjs",
+            "default": "./dist/index.js"
+        },
+        "./errors": {
+            "types": "./dist/types/errors.d.ts",
+            "require": "./dist/lib.commonjs/errors.cjs",
+            "default": "./dist/lib.esm/errors.js"
+        },
+        "./types": {
+            "types": "./dist/types/types.d.ts",
+            "require": "./dist/lib.commonjs/types.cjs",
+            "default": "./dist/lib.esm/types.js"
+        }
+    },
+    "files": [
+        "dist/",
+        "src/",
+        "LICENSE",
+        "README.md"
+    ],
+    "repository": "https://github.com/semaphore-protocol/semaphore",
+    "homepage": "https://github.com/semaphore-protocol/semaphore/tree/main/packages/utils",
+    "bugs": {
+        "url": "https://github.com/semaphore-protocol/semaphore.git/issues"
+    },
+    "scripts": {
+        "build": "rimraf dist && rollup -c rollup.config.ts --configPlugin typescript",
+        "prepublishOnly": "yarn build"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "rollup-plugin-cleanup": "^3.2.1",
+        "rollup-plugin-typescript2": "^0.36.0"
+    }
+}

packages/utils/rollup.config.ts

@@ -0,0 +1,30 @@
+import * as fs from "fs"
+import cleanup from "rollup-plugin-cleanup"
+import typescript from "rollup-plugin-typescript2"
+
+const pkg = JSON.parse(fs.readFileSync("./package.json", "utf-8"))
+const banner = `/**
+ * @module ${pkg.name}
+ * @version ${pkg.version}
+ * @file ${pkg.description}
+ * @copyright Ethereum Foundation 2024
+ * @license ${pkg.license}
+ * @see [Github]{@link ${pkg.homepage}}
+*/`
+
+export default {
+    input: "src/index.ts",
+    output: [
+        { file: pkg.exports["."].require, format: "cjs", banner, exports: "auto" },
+        { file: pkg.exports["."].default, format: "es", banner },
+        { dir: "./dist/lib.commonjs", format: "cjs", banner, preserveModules: true },
+        { dir: "./dist/lib.esm", format: "es", banner, preserveModules: true }
+    ],
+    plugins: [
+        typescript({
+            tsconfig: "./build.tsconfig.json",
+            useTsconfigDeclarationDir: true
+        }),
+        cleanup({ comments: "jsdoc" })
+    ]
+}

packages/utils/src/errors.ts

@@ -0,0 +1,108 @@
+/**
+ * @module Errors
+ * This module is designed to provide utility functions for validating
+ * function parameters. It includes functions that throw type errors if
+ * the parameters do not meet specified criteria, such as being defined,
+ * a number, a string, a function, or an array. This module helps ensure
+ * that functions receive the correct types of inputs, enhancing code
+ * reliability and reducing runtime errors.
+ */
+
+import {
+    SupportedType,
+    isArray,
+    isDefined,
+    isFunction,
+    isNumber,
+    isString,
+    isSupportedType,
+    isType,
+    isUint8Array
+} from "./types"
+
+/**
+ * It throws a type error if the parameter value has not been defined.
+ * @param parameterValue The parameter value.
+ * @param parameterName The parameter name.
+ */
+export function requireDefined(parameterValue: any, parameterName: string) {
+    if (!isDefined(parameterValue)) {
+        throw new TypeError(`Parameter '${parameterName}' is not defined`)
+    }
+}
+
+/**
+ * It throws a type error if the parameter value is not a number.
+ * @param parameterValue The parameter value.
+ * @param parameterName The parameter name.
+ */
+export function requireNumber(parameterValue: number, parameterName: string) {
+    if (!isNumber(parameterValue)) {
+        throw new TypeError(`Parameter '${parameterName}' is not a number`)
+    }
+}
+
+/**
+ * It throws a type error if the parameter value is not a string.
+ * @param parameterValue The parameter value.
+ * @param parameterName The parameter name.
+ */
+export function requireString(parameterValue: string, parameterName: string) {
+    if (!isString(parameterValue)) {
+        throw new TypeError(`Parameter '${parameterName}' is not a string`)
+    }
+}
+
+/**
+ * It throws a type error if the parameter value is not a function.
+ * @param parameterValue The parameter value.
+ * @param parameterName The parameter name.
+ */
+export function requireFunction(parameterValue: Function, parameterName: string) {
+    if (!isFunction(parameterValue)) {
+        throw new TypeError(`Parameter '${parameterName}' is not a function`)
+    }
+}
+
+/**
+ * It throws a type error if the parameter value is not an array.
+ * @param parameterValue The parameter value.
+ * @param parameterName The parameter name.
+ */
+export function requireArray(parameterValue: any[], parameterName: string) {
+    if (!isArray(parameterValue)) {
+        throw new TypeError(`Parameter '${parameterName}' is not an array`)
+    }
+}
+
+/**
+ * It throws a type error if the parameter value is not a uint8array.
+ * @param parameterValue The parameter value.
+ * @param parameterName The parameter name.
+ */
+export function requireUint8Array(parameterValue: Uint8Array, parameterName: string) {
+    if (!isUint8Array(parameterValue)) {
+        throw new TypeError(`Parameter '${parameterName}' is not a Uint8Array`)
+    }
+}
+
+/**
+ * It throws a type error if the parameter value type is not part of the list of types.
+ * @param parameterValue The parameter value.
+ * @param parameterName The parameter name.
+ */
+export function requireTypes(parameterValue: any, parameterName: string, types: SupportedType[]) {
+    for (const type of types) {
+        if (!isSupportedType(type)) {
+            throw new Error(`Type '${type}' is not supported`)
+        }
+    }
+
+    for (const type of types) {
+        if (isType(parameterValue, type)) {
+            return
+        }
+    }
+
+    throw new TypeError(`Parameter '${parameterName}' is none of the following types: ${types.join(", ")}`)
+}

packages/utils/src/index.ts

@@ -0,0 +1,4 @@
+import * as errors from "./errors"
+import * as types from "./types"
+
+export { errors, types }