feat: add @zk-kit/logical-expressions package (#310)

* feat: add package logical-expressions

This is a new package to evaluate logical expressions.

re #307

* refactor(logical-expressions): throw an error if the logical expression is incorrect

The algorithm throws an error if the logical expression is incorrect, eliminating the need for
previous validation.

re #307

* refactor(logical-expressions): throw an error if the logical expression is empty

re #307

* docs(logical-expressions): add instructions to install and use the package

re #307

* docs: update repo readme and codeowners files

re #307

* docs(logical-expressions): improve code documentation

re #307

* refactor(logical-expressions): export the applyOperator function

re #307

* refactor(logical-expressions): export the precedence function

re #307

* docs(logical-expressions): update evaluate function docs

re #307

* docs(logical-expressions): update code docs

re #307

* chore(logical-expressions): update package json file

.github/CODEOWNERS

@@ -14,3 +14,4 @@
 /packages/poseidon-proof/ @cedoor @vplasencia @0xjei
 /packages/imt/ @cedoor
 /packages/utils/ @cedoor @artwyman
+/packages/logical-expressions/ @vplasencia

README.md

@@ -336,6 +336,37 @@
                 ❌
             </td>
         </tr>
+        <tr>
+            <td>
+                <a href="https://github.com/privacy-scaling-explorations/zk-kit/tree/main/packages/logical-expressions">
+                    @zk-kit/logical-expressions
+                </a>
+                 <a href="https://zkkit.pse.dev/modules/_zk_kit_poseidon_proof.html">
+                    (docs)
+                </a>
+            </td>
+            <td>
+                <!-- NPM version -->
+                <a href="https://npmjs.org/package/@zk-kit/logical-expressions">
+                    <img src="https://img.shields.io/npm/v/@zk-kit/logical-expressions.svg?style=flat-square" alt="NPM version" />
+                </a>
+            </td>
+            <td>
+                <!-- Downloads -->
+                <a href="https://npmjs.org/package/@zk-kit/logical-expressions">
+                    <img src="https://img.shields.io/npm/dm/@zk-kit/logical-expressions.svg?style=flat-square" alt="Downloads" />
+                </a>
+            </td>
+            <td>
+                <!-- Size -->
+                <a href="https://bundlephobia.com/package/@zk-kit/logical-expressions">
+                    <img src="https://img.shields.io/bundlephobia/minzip/@zk-kit/logical-expressions" alt="npm bundle size (scoped)" />
+                </a>
+            </td>
+            <td>
+                ❌
+            </td>
+        </tr>
     <tbody>
 </table>
 

package.json

@@ -11,7 +11,7 @@
         "build": "turbo _build",
         "_test": "jest --coverage",
         "test": "turbo _test",
-        "test:library": "jest packages/${0}",
+        "test:library": "jest --coverage packages/${0}",
         "version:bump": "yarn workspace @zk-kit/${0} version ${1} && yarn remove:stable-version-field ${0} && NO_HOOK=1 git commit -am \"chore(${0}): v${1}\" && git tag ${0}-v${1}",
         "version:publish": "yarn workspaces foreach -A --no-private npm publish --tolerate-republish --access public",
         "version:release": "changelogithub",

packages/logical-expressions/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/logical-expressions/README.md

@@ -0,0 +1,153 @@
+<p align="center">
+    <h1 align="center">
+        Logical Expressions
+    </h1>
+    <p align="center">A library to evaluate logical expressions.</p>
+</p>
+
+<p align="center">
+    <a href="https://github.com/privacy-scaling-explorations/zk-kit">
+        <img src="https://img.shields.io/badge/project-zk--kit-blue.svg?style=flat-square">
+    </a>
+    <a href="https://github.com/privacy-scaling-explorations/zk-kit/tree/main/packages/logical-expressions/LICENSE">
+        <img alt="NPM license" src="https://img.shields.io/npm/l/%40zk-kit%2Flogical-expressions?style=flat-square">
+    </a>
+    <a href="https://www.npmjs.com/package/@zk-kit/logical-expressions">
+        <img alt="NPM version" src="https://img.shields.io/npm/v/@zk-kit/logical-expressions?style=flat-square" />
+    </a>
+    <a href="https://npmjs.org/package/@zk-kit/logical-expressions">
+        <img alt="Downloads" src="https://img.shields.io/npm/dm/@zk-kit/logical-expressions.svg?style=flat-square" />
+    </a>
+    <a href="https://bundlephobia.com/package/@zk-kit/logical-expressions">
+        <img alt="npm bundle size (scoped)" src="https://img.shields.io/bundlephobia/minzip/@zk-kit/logical-expressions" />
+    </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://appliedzkp.org/discord">
+            🗣️ Chat &amp; Support
+        </a>
+        <span>&nbsp;&nbsp;|&nbsp;&nbsp;</span>
+        <a href="https://zkkit.pse.dev/modules/_zk_kit_logical_expressions.html">
+            📘 Docs
+        </a>
+    </h4>
+</div>
+
+| This library facilitates the work with logical (boolean) expressions. It allows you to tokenize and evaluate any logical expression. It supports the use of parentheses. |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+
+## 🛠 Install
+
+### npm or yarn
+
+Install the `@zk-kit/logical-expressions` package with npm:
+
+```bash
+npm i @zk-kit/logical-expressions
+```
+
+or yarn:
+
+```bash
+yarn add @zk-kit/logical-expressions
+```
+
+### CDN
+
+You can also load it using a `script` tag using [unpkg](https://unpkg.com/):
+
+```html
+<script src="https://unpkg.com/@zk-kit/logical-expressions"></script>
+```
+
+or [JSDelivr](https://www.jsdelivr.com/):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@zk-kit/logical-expressions"></script>
+```
+
+## 📜 Usage
+
+Supported logical operators: `and`, `or`, `not`, `xor`.
+
+All other existing logical operators (`nand`, `nor`, `xnor`) can be generated using the supported logical operators.
+
+## Tokenize a logical expression
+
+\# **tokenize**(): _string[]_
+
+Tokenizes a logical (boolean) expression.
+Splits the expression into meaningful tokens.
+
+```ts
+import { tokenize } from "@zk-kit/logical-expressions"
+
+const expression = "true and false or ( true and true )"
+
+const tokens = tokenize(expression)
+
+console.log(tokens)
+// Output: ["true", "and", "false", "or", "(", "true", "and", "true", ")"]
+```
+
+## Precedence of a logical operator
+
+\# **precedence**(): _number_
+
+Returns the precedence of a logical operator. If the operator is not supported, the precedence will be 0.
+
+```ts
+import { precedence } from "@zk-kit/logical-expressions"
+
+const result = precedence("and")
+
+console.log(result) // Output: 1
+```
+
+## Apply Operator
+
+\# **applyOperator**(): _boolean_
+
+Applies unary or binary operators to boolean values.
+
+```ts
+import { applyOperator } from "@zk-kit/logical-expressions"
+
+// Unary operator
+const result1 = applyOperator("not", true)
+console.log(result1) // Output: false
+
+// Binary operator
+const result2 = applyOperator("and", true, false)
+console.log(result2) // Output: false
+```
+
+## Evaluate a tokenized logical expression
+
+\# **evaluate**(): _boolean_
+
+Evaluates a tokenized logical (boolean) expression.
+
+There is no need to verify the correctness of the logical expression before calling the evaluate function, as this will be checked during the evaluation. If the expression is incorrect, an error will be thrown automatically.
+
+Example of correct logical expression: `"true and false"`.
+
+Example of incorrect logical expression: `"true true and false"`.
+
+```ts
+import { evaluate } from "@zk-kit/logical-expressions"
+
+const expression = ["true", "and", "false"]
+
+const result = evaluate(expression)
+
+console.log(result) // Output: false
+```

packages/logical-expressions/build.tsconfig.json

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

packages/logical-expressions/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "@zk-kit/logical-expressions",
+    "version": "1.0.0",
+    "description": "A library to evaluate logical expressions.",
+    "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"
+        }
+    },
+    "files": [
+        "dist/",
+        "src/"
+    ],
+    "repository": "[email protected]:privacy-scaling-explorations/zk-kit.git",
+    "homepage": "https://github.com/privacy-scaling-explorations/zk-kit/tree/main/packages/logical-expressions",
+    "bugs": {
+        "url": "https://github.com/privacy-scaling-explorations/zk-kit.git/issues"
+    },
+    "author": {
+        "name": "Vivian Plasencia",
+        "email": "[email protected]",
+        "url": "https://github.com/vplasencia"
+    },
+    "scripts": {
+        "build": "rimraf dist && rollup -c rollup.config.ts --configPlugin typescript",
+        "prepublishOnly": "yarn build"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "@rollup/plugin-typescript": "^11.1.6",
+        "rimraf": "^5.0.5",
+        "rollup": "^4.12.0",
+        "rollup-plugin-cleanup": "^3.2.1"
+    }
+}

packages/logical-expressions/rollup.config.ts

@@ -0,0 +1,22 @@
+import typescript from "@rollup/plugin-typescript"
+import fs from "fs"
+import cleanup from "rollup-plugin-cleanup"
+
+const pkg = JSON.parse(fs.readFileSync("./package.json", "utf8"))
+const banner = `/**
+ * @module ${pkg.name}
+ * @version ${pkg.version}
+ * @file ${pkg.description}
+ * @copyright Ethereum Foundation ${new Date().getFullYear()}
+ * @license ${pkg.license}
+ * @see [Github]{@link ${pkg.homepage}}
+*/`
+
+export default {
+    input: "src/index.ts",
+    output: [
+        { file: pkg.exports["."].require, format: "cjs", banner },
+        { file: pkg.exports["."].default, format: "es", banner }
+    ],
+    plugins: [typescript({ tsconfig: "./build.tsconfig.json" }), cleanup({ comments: "jsdoc" })]
+}