sqlstack 1.0.0

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "sqlstack",
+  "version": "1.0.0",
+  "description": "",
+  "license": "ISC",
+  "author": "",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "require": "./dist/registry.js",
+      "import": "./dist/registry.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "require": "./dist/adapters/index.js",
+      "import": "./dist/adapters/index.js"
+    },
+    "./errors": {
+      "types": "./dist/core/errors.d.ts",
+      "require": "./dist/core/errors.js",
+      "import": "./dist/core/errors.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "clean": "rimraf dist",
+    "test:integration": "jest -c jest.integration.config.ts",
+    "db:pg:up": "docker compose -f docker/docker-compose.pg.yml up -d",
+    "db:pg:down": "docker compose -f docker/docker-compose.pg.yml down -v",
+    "db:mysql:up": "docker compose -f docker/docker-compose.mysql.yml up -d",
+    "db:mysql:down": "docker compose -f docker/docker-compose.mysql.yml down -v",
+    "db:ps": "docker ps --filter name=sqlstack-",
+    "db:logs:pg": "docker logs -f sqlstack-postgres",
+    "db:logs:mysql": "docker logs -f sqlstack-mysql"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.13",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.2"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^2.1.1",
+    "reflect-metadata": "^0.1.13",
+    "sqlite": "^5.1.1"
+  },
+  "peerDependencies": {
+    "better-sqlite3": "^9.6.0",
+    "mysql2": "^3.14.4",
+    "pg": "^8.16.3",
+    "sqlite3": "^5.1.7"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "sqlite3": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20 <23"
+  }
+}

package/readme.md

@@ -0,0 +1,376 @@
+# sqlstack
+
+SQL-first data access for Node.js and TypeScript.
+
+Write real SQL, keep it next to your code, and use small, composable decorators to add behavior like defaults, single-row results, and result validation — without ORM complexity.
+
+- Real SQL in `.sql` files
+- TypeScript-first: declare args/return types yourself, or plug in validation/typegen
+- Composable decorators: `@Single`, `@Only`, `@Exist`, `@Defaults`, `@ValidateResult` (order-independent)
+- Minimal runtime: a thin executor layer on top of your DB driver
+- Works with Postgres, MySQL/MariaDB, SQLite (more adapters coming)
+- Structured errors via `SqlStackError` base class
+ - Configurable connections via a simple registry (per-class and per-method)
+
+## Install
+
+```bash
+npm install sqlstack
+# or
+yarn add sqlstack
+# or
+pnpm add sqlstack
+```
+
+Install a database driver as needed:
+
+```bash
+npm install pg             # Postgres
+npm install mysql2         # MySQL / MariaDB
+npm install better-sqlite3 # SQLite
+```
+
+## Configure Databases
+
+Register your database connections once at application startup and set a default.
+
+boot.ts
+
+```ts
+// boot.ts — register your connections
+import { SqlStackDB } from "sqlstack/registry";
+import { createPgDb, createMysqlDb, createSqliteDb } from "sqlstack/adapters";
+
+SqlStackDB
+  .register("primary",   createPgDb(process.env.PG_URL!))
+  .register("analytics", createMysqlDb(process.env.MYSQL_URL!))
+  .register("test",      createSqliteDb(":memory:"))
+  .setDefault("primary");
+```
+
+Then, choose a database per repository (class-level default):
+
+```ts
+import { QueryBinder, Query, SqlStackError } from "sqlstack";
+
+@QueryBinder({ db: "analytics" }) // class default
+export class ReportsRepo {
+  // Uses "analytics" unless overridden below
+  @Query()
+  async topPages(_a: { since: string }): Promise<Row[]> {
+    throw new SqlStackError("replaced");
+  }
+}
+```
+
+Load `boot.ts` once during app startup (for example, in your server entry).
+
+Per-method override (use a different DB for a specific query):
+
+```ts
+import { QueryBinder, Query, SqlStackError } from "sqlstack";
+
+@QueryBinder({ db: "primary" }) // default for this class
+export class MixedRepo {
+  @Query() // uses "primary"
+  async dailySummary(_a: { date: string }): Promise<Row[]> {
+    throw new SqlStackError("replaced");
+  }
+
+  @Query({ db: "analytics" }) // override to use "analytics"
+  async topPages(_a: { since: string }): Promise<Row[]> {
+    throw new SqlStackError("replaced");
+  }
+}
+```
+
+## Quick Start
+
+1) Create a repository class
+
+```ts
+import { QueryBinder, Query, SqlStackError } from "sqlstack";
+
+@QueryBinder() // looks for .sql files in the same folder by default
+export class UsersRepo {
+  @Query()
+  async findByEmail(_a: { email: string }): Promise<User[]> {
+    throw new SqlStackError("replaced by @Query");
+  }
+}
+```
+
+2) Add the SQL file next to your class
+
+```
+users/
+  index.ts
+  findByEmail.sql
+```
+
+findByEmail.sql
+
+```sql
+SELECT id, email, name, status, created_at
+FROM users
+WHERE email = :email;
+```
+
+3) Call your repository
+
+```ts
+const repo = new UsersRepo();
+const rows = await repo.findByEmail({ email: "alice@example.com" });
+```
+
+## SQL Parameters
+
+Write parameters directly in your `.sql` files and pass values from your method call.
+
+### Named parameters
+
+Use `:name` placeholders that map to properties of a single object argument.
+
+```sql
+-- findByEmail.sql
+SELECT id, email, name, status
+FROM users
+WHERE email = :email AND status = :status;
+```
+
+```ts
+await repo.findByEmail({ email: "alice@example.com", status: "active" });
+```
+
+### Positional parameters
+
+Use `:arg1`, `:arg2`, … and pass values by position. Indexing starts at 1.
+
+```sql
+-- findById.sql
+SELECT *
+FROM users
+WHERE id = :arg1 AND org_id = :arg2;
+```
+
+```ts
+await repo.findById("user-123", "org-456");
+```
+
+Use either named or positional parameters within a single query (do not mix both).
+
+### Array parameters
+
+Pass arrays to expand into `IN (...)` lists.
+
+```sql
+-- listByIds.sql
+SELECT *
+FROM users
+WHERE id IN (:ids);
+```
+
+```ts
+await repo.listByIds({ ids: ["user-1", "user-2", "user-3"] });
+```
+
+Note: For empty arrays, prefer an early return in your code (e.g., `if (!ids.length) return [];`) to avoid generating invalid SQL.
+
+### Null and undefined
+
+- `null` maps to SQL `NULL`.
+- `undefined` is not allowed and will throw; provide a value or omit the parameter entirely.
+
+## SQL File Resolution
+
+`@Query()` loads SQL from files based on a simple, predictable rule:
+
+- No argument: resolves from the declaring file’s folder.
+- File path: resolves from `dirname(filePath)`.
+- Folder path: resolves directly from that folder.
+
+For each method name, sqlstack looks for `<method>.<dialect>.sql` first, then `<method>.sql`. Dialect suffixes: `.pg.sql`, `.mysql.sql`, `.sqlite.sql`. Resolution and file contents are cached. See docs/file_resolution.md for details.
+
+## Decorators
+
+### `@Defaults`
+
+Provide default parameter values.
+
+```ts
+import { QueryBinder, Defaults, Query, SqlStackError } from "sqlstack";
+
+@QueryBinder()
+class UsersRepo {
+  @Defaults({ status: "active", limit: 10 })
+  @Query()
+  async listUsers(_a: { status?: string; limit?: number }): Promise<User[]> {
+    throw new SqlStackError();
+  }
+}
+```
+
+- Calling `repo.listUsers({})` fills `{ status: "active", limit: 10 }`.
+
+### Result shape decorators
+
+Choose a decorator to shape row results without parameters.
+
+```ts
+import { QueryBinder, Single, Only, Exist, None, Query, SqlStackError } from "sqlstack";
+
+@QueryBinder()
+class UsersRepo {
+  // @Single → return the first row or null
+  @Single
+  @Query()
+  async firstOrNull(_a: { email: string }): Promise<User | null> {
+    throw new SqlStackError();
+  }
+
+  // @Only → require exactly one row; throw if 0 or >1
+  @Only
+  @Query()
+  async exactlyOne(_a: { id: string }): Promise<User> {
+    throw new SqlStackError();
+  }
+
+  // @Exist → require at least one row; return first row; throw if none
+  @Exist
+  @Query()
+  async requireOne(_a: { email: string }): Promise<User> {
+    throw new SqlStackError();
+  }
+
+  // @None → require zero rows; return null; throw if any rows
+  @None
+  @Query()
+  async ensureNone(_a: { status: string }): Promise<null> {
+    throw new SqlStackError();
+  }
+}
+```
+
+### `@ValidateResult`
+
+Validate query results with JSON Schema.
+
+```ts
+import schema from "./user.row.schema.json" assert { type: "json" };
+import { QueryBinder, ValidateResult, Single, Query, SqlStackError } from "sqlstack";
+
+@QueryBinder()
+class UsersRepo {
+  @ValidateResult(schema)
+  @Single
+  @Query()
+  async findByEmail(_a: { email: string }): Promise<User | null> {
+    throw new SqlStackError();
+  }
+}
+```
+
+ 
+
+## Inline Builders
+
+Intentionally not included. sqlstack prioritizes explicit `.sql` files for clarity and control.
+
+## JSON Schema
+
+Add a JSON Schema file and attach it to a method with `@ValidateResult`.
+
+user.row.schema.json
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string" },
+    "email": { "type": "string", "format": "email" },
+    "status": { "enum": ["active", "inactive"] }
+  },
+  "required": ["id", "email", "status"],
+  "additionalProperties": false
+}
+```
+
+Usage
+
+```ts
+import schema from "./user.row.schema.json" assert { type: "json" };
+import { QueryBinder, ValidateResult, Query } from "sqlstack";
+
+@QueryBinder()
+class UsersRepo {
+  @ValidateResult(schema)
+  @Query()
+  async listUsers(): Promise<User[]> {
+    // executes and validates each row against the schema
+  }
+}
+```
+
+## Errors
+
+sqlstack provides a base error and specific error types you can import and catch.
+
+```ts
+import { SqlStackError } from "sqlstack";
+import { ExactlyOneRowError, NoRowsError, ValidationError } from "sqlstack/errors";
+
+try {
+  // call repository methods
+} catch (err) {
+  if (err instanceof ExactlyOneRowError) {
+    // @Only: expected exactly one row
+  }
+  if (err instanceof NoRowsError) {
+    // @Exist: expected at least one row
+  }
+  if (err instanceof ValidationError) {
+    // @ValidateResult: schema mismatch
+  }
+  if (err instanceof SqlStackError) {
+    // handle sqlstack-specific failures
+  }
+  throw err;
+}
+```
+
+
+## Philosophy
+
+- SQL-first: SQL is the source of truth. No hidden queries.
+- Decorators as metadata: `@Defaults`, `@Single`, `@Only`, `@Exist`, `@ValidateResult` add labels; execution order is fixed internally, so decorator order doesn’t matter.
+- Escape hatches: Use inline builders for simple CRUD; keep complex SQL in `.sql` files. You stay in control.
+
+### Execution Pipeline
+
+At runtime, decorators execute in a fixed, predictable order regardless of source order:
+
+1) Defaults → 2) Query → 3) Single/Only/Exist → 4) ValidateResult. See docs/decorators.md for the model and examples.
+
+### Validation Controls
+
+- Default: validation is enabled.
+- Env toggles (precedence):
+  - `SQLSTACK_ENABLE_VALIDATION` truthy → force ON (even in production)
+  - else if `SQLSTACK_DISABLE_VALIDATION` truthy → force OFF
+  - else → ON
+
+## Database Support
+
+- Postgres (`pg`)
+- MySQL / MariaDB (`mysql2`)
+- SQLite (`better-sqlite3`)
+
+More adapters are planned.
+
+### Dialect Inference
+
+The binder placeholder style is inferred from the selected database (method → class → registry default). Only override via `@Query({ dialect })` if you need to force a specific dialect.
+
+## License
+
+ISC