kanun 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Toneflix, LLC. and Arcstack Contributors
+
+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.

package/README.md

@@ -0,0 +1,171 @@
+# Kanun
+
+[![Validation Package Version][i1]][l1]
+[![Downloads][d1]][l1]
+[![Tests][tei]][tel]
+[![License][lini]][linl]
+
+Lightweight framework-agnostic and TypeScript-first validation library. Provides a rich set of built-in rules, custom rule support, nested data validation, conditional rules, localized error messages, and a flexible API for validating complex data structures in Node.js applications.
+
+## Installation
+
+```bash
+npm install kanun
+```
+
+## Features
+
+- Rule-based validation — Supports common rules like required, min, max, email, url, numeric, boolean, in, regex, etc.
+- Nested data validation — Dot notation for nested objects (user.email, items.\*.price).
+- Custom error messages — Per-rule and per-field message overrides.
+- Batch validation — Validate multiple datasets or groups in one call.
+- Conditional validation — Rules that only apply when other fields meet conditions (required_if, sometimes, exclude_unless).
+- Implicit rules — Rules that run even when attributes are missing (e.g., accepted, required).
+
+- Custom rules — Define user-provided validation rules as functions or classes.
+- Async rules — Support for async validation (e.g., checking uniqueness in a database).
+- Attribute sanitization — Optional transformation (e.g., trimming, normalizing case) before validation.
+- Dynamic rule sets — Rules can be generated at runtime (e.g., based on user roles).
+- Dependent rules — Rules that reference other fields dynamically.
+
+- Localized error messages — Built-in support for localization and i18n message templates.
+- Structured errors — Validation errors returned as structured objects or flat key–message pairs.
+- Fail-fast mode — Option to stop at the first failure or collect all errors.
+- Human-readable summaries — Helper for formatting readable validation reports.
+
+- TypeScript-first design — Full type inference for rules, messages, and validated data.
+- Chainable API — Optional fluent syntax for building validators.
+
+## Usage
+
+### Quick Start
+
+```ts
+import { Validator } from 'kanun';
+
+const validator = new Validator(
+  { email: 'john@example.com', age: 20 },
+  { email: 'required|email', age: 'required|numeric|min:18' },
+);
+
+const passes = await validator.passes();
+
+if (!passes) {
+  console.log(validator.errors().all());
+}
+```
+
+### Throwing Validation Errors
+
+```ts
+import { Validator, ValidationException } from 'kanun';
+
+const validator = Validator.make({ email: '' }, { email: 'required|email' });
+
+try {
+  const data = await validator.validate();
+  console.log(data);
+} catch (error) {
+  if (error instanceof ValidationException) {
+    console.log(error.errors());
+  }
+}
+```
+
+### Custom Messages
+
+```ts
+const validator = new Validator(
+  { email: '' },
+  { email: 'required|email' },
+  {
+    'email.required': 'Email is required.',
+    'email.email': 'Email must be valid.',
+  },
+);
+```
+
+### Nested and Array Validation
+
+```ts
+const validator = new Validator(
+  {
+    user: { name: { first: 'John', last: '' } },
+    users: [{ email: 'good@example.com' }, { email: 'bad' }],
+  },
+  {
+    'user.name.first': 'required|min:2',
+    'user.name.last': 'required|min:2',
+    'users.*.email': 'required|email',
+  },
+);
+```
+
+### Custom Rule Class
+
+```ts
+import { ValidationRule, Validator } from 'kanun';
+
+class StartsWithKanun extends ValidationRule {
+  validate(
+    attribute: string,
+    value: any,
+    fail: (message: string) => void,
+  ): void {
+    if (typeof value !== 'string' || !value.startsWith('kanun')) {
+      fail(`The ${attribute} must start with kanun.`);
+    }
+  }
+}
+
+const validator = new Validator(
+  { slug: 'kanun' },
+  { slug: ['required', new StartsWithKanun()] },
+);
+```
+
+### Database-backed `exists` and `unique`
+
+```ts
+import { IDatabaseDriver, Validator } from 'kanun';
+
+class AppDatabaseDriver extends IDatabaseDriver {
+  async exists({ table, column, value, ignore }) {
+    const row = await db.table(table).where(column, value).first();
+    if (!row) return false;
+    if (ignore != null && String(row.id) === String(ignore)) return false;
+    return true;
+  }
+}
+
+const driver = new AppDatabaseDriver();
+
+Validator.useDatabase(driver);
+
+const validator = new Validator(
+  { username: 'legacy' },
+  { username: 'unique:users,username' },
+);
+```
+
+For the complete guide and API reference, visit the docs site: https://arcstack-hq.github.io/kanun
+
+## Code of Conduct
+
+In order to ensure that the Kanun community is welcoming to all, please review and abide by the [Code of Conduct](https://arcstack-hq.github.io/code-of-conduct).
+
+## Security Vulnerabilities
+
+If you discover a security vulnerability within Kanun, please send an e-mail to Legacy via hi@toneflix.net. All security vulnerabilities will be promptly addressed.
+
+## License
+
+Kanun and all Arcstack packages are open source and licensed under the [MIT license](LICENSE).
+
+[i1]: https://img.shields.io/npm/v/%40kanun?style=flat-square&label=kanun&color=%230970ce
+[l1]: https://www.npmjs.com/package/kanun
+[d1]: https://img.shields.io/npm/dt/%40kanun?style=flat-square&label=Downloads&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40kanun
+[linl]: https://github.com/arcstack-hq/kanun/blob/main/LICENSE
+[lini]: https://img.shields.io/github/license/arcstack-hq/kanun
+[tel]: https://github.com/arcstack-hq/kanun/actions/workflows/ci.yml
+[tei]: https://github.com/arcstack-hq/kanun/actions/workflows/ci.yml/badge.svg