@streetjs/repository 1.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,72 @@
+# Architecture — @streetjs/repository
+
+## Purpose
+
+`@streetjs/repository` is the StreetJS data-access base layer: a generic,
+strongly-typed CRUD repository over a PostgreSQL pool, plus a small atomic
+"ledger" transaction helper. Domain repositories in an application extend
+`StreetPostgresRepository<T>` and supply a table name and a row mapper.
+
+## Dependencies
+
+```
+@streetjs/pool      (PgPool — the query/transaction/stream surface)
+@streetjs/postgres  (PgConnection + StreetPostgresWireStream types)
+```
+
+No cyclic dependencies. Field-level encryption is decoupled via a structural
+`FieldEncryptor` interface, so this package does **not** depend on the enterprise
+data-policy module — any object with `encryptEntity`/`decryptEntity` qualifies
+(the framework's `FieldEncryptor` class satisfies it structurally).
+
+## Design
+
+### Typed CRUD over parameterized SQL
+
+`StreetPostgresRepository<T>` is abstract: subclasses declare `tableName` and
+implement `mapRow(row)`. Every method issues **parameterized** queries
+(`$1..$N`); values are never interpolated. `create`/`update` build column and
+placeholder lists from the object's own keys, skipping `undefined` values.
+`findAll` clamps `limit` into `[1, 1000]` and floors `offset` at `0` to bound
+result sizes.
+
+### Table-name safety
+
+The only identifier that can't be parameterized is the table name. It is
+validated against `^[a-zA-Z_][a-zA-Z0-9_.]*$` **lazily on first query** (the
+abstract property isn't available in the base constructor), so a mis-declared
+subclass fails fast with a clear error instead of emitting injectable SQL.
+
+### Optional transparent encryption
+
+When a subclass sets both `encryptor` (a `FieldEncryptor`) and `encryptedEntity`
+(the annotated entity class), `create`/`update` run values through
+`encryptEntity` before writing and `findById`/`findAll`/`create`/`update` run
+returned rows through `decryptEntity`. When either is unset, both paths are
+no-ops — zero overhead for repositories that don't opt in.
+
+### Transactions and streaming
+
+`withTransaction(fn)` delegates to `pool.transaction`, giving `fn` a single
+connection with BEGIN/COMMIT (ROLLBACK on throw). `streamAll(sql)` delegates to
+`pool.stream` for backpressured reads; parameterized streaming is not yet
+supported and throws synchronously to steer callers to `pool.query`.
+`LedgerTransactionService.execute(ops, onSuccess?)` runs a list of operations and
+an optional success callback within one transaction.
+
+## Testing
+
+The suite runs with **no live database** using a fake pool that records queries
+and returns scripted results. It covers all CRUD paths (including limit/offset
+clamping, undefined-field skipping, empty-update fallthrough, and the
+delete/insert edge cases), lazy table-name rejection, the encrypt-on-write /
+decrypt-on-read cycle via a fake `FieldEncryptor`, streaming (both the
+parameterized rejection and the delegation path), `withTransaction`, and the
+ledger service with and without a success callback. Coverage is 100%.
+
+## Non-goals
+
+- No query builder, joins, or relations — this is a single-table CRUD base.
+- No schema management (see `@streetjs/migrations`).
+- No connection management (see `@streetjs/pool`).
+- No encryption implementation — only the structural hook to plug one in.

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `@streetjs/repository` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0]
+
+### Added
+
+- Initial standalone release of the StreetJS generic repository, extracted
+  verbatim from the `streetjs` core (`src/database/repository.ts`).
+- `StreetPostgresRepository<T>` abstract base: typed `findById`, `findAll`
+  (with clamped pagination), `create`, `update`, `delete`, `count`,
+  `withTransaction`, and `streamAll`, all over parameterized SQL with lazy
+  table-name validation.
+- Optional transparent field-level encryption via a structural `FieldEncryptor`
+  hook (`encryptor` + `encryptedEntity`), decoupled from the data-policy module.
+- `LedgerTransactionService` for atomic multi-operation transactions.
+- Public types: `IRepository<T>`, `FieldEncryptor`.
+- Runs on `@streetjs/pool` and `@streetjs/postgres`; ESM. 19 tests (no live
+  database) with 100% coverage and a runnable example.
+
+[1.0.0]: https://github.com/hassanmubiru/StreetJS/releases/tag/repository-v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 street 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,116 @@
+# @streetjs/repository
+
+The StreetJS generic PostgreSQL repository: a typed CRUD base class over
+[`@streetjs/pool`](https://www.npmjs.com/package/@streetjs/pool) with safe
+identifier validation, pagination, streaming, transactions, and **optional
+transparent field-level encryption**. Plus `LedgerTransactionService` for
+running a sequence of operations atomically. ESM, strict-TypeScript.
+
+This is the standalone home of the repository that also backs the
+`streetjs/repository` subpath. The `streetjs` framework re-exports this package,
+so there is a single source of truth.
+
+## Install
+
+```bash
+npm install @streetjs/repository @streetjs/pool
+```
+
+## Usage
+
+```ts
+import { StreetPostgresRepository } from '@streetjs/repository';
+
+interface User { id: string; name: string; email: string }
+
+class UserRepository extends StreetPostgresRepository<User> {
+  protected readonly tableName = 'users';
+  protected mapRow(row: Record<string, string | null>): User {
+    return { id: row.id!, name: row.name!, email: row.email! };
+  }
+}
+
+const users = new UserRepository(pool); // a PgPool
+
+await users.create({ id: '1', name: 'Ada', email: 'ada@x.dev' });
+await users.findById('1');
+await users.findAll(20, 0);      // limit clamped to [1, 1000], offset floored at 0
+await users.update('1', { name: 'Ada L.' });
+await users.count();
+await users.delete('1');
+```
+
+Subclasses provide a `tableName` and a `mapRow` that turns a raw row into your
+entity. All queries are parameterized; the table name is validated against
+`^[a-zA-Z_][a-zA-Z0-9_.]*$` on first use to prevent SQL injection through a
+mis-declared subclass.
+
+## Transactions & streaming
+
+```ts
+// Run arbitrary work on a single connection in a transaction:
+await users.withTransaction(async (conn) => {
+  await conn.query('UPDATE users SET name = $1 WHERE id = $2', ['Neo', '1']);
+});
+
+// Stream a large result set with backpressure:
+const stream = await users.streamAll('SELECT * FROM users');
+```
+
+`LedgerTransactionService` runs a list of operations and an optional success
+callback atomically:
+
+```ts
+import { LedgerTransactionService } from '@streetjs/repository';
+
+await new LedgerTransactionService(pool).execute(
+  [
+    (conn) => conn.query('INSERT INTO ledger ...'),
+    (conn) => conn.query('UPDATE balances ...'),
+  ],
+  async () => 'committed',
+);
+```
+
+## Transparent field-level encryption
+
+Set `encryptor` and `encryptedEntity` on a subclass to automatically encrypt
+`@Encrypt()`-annotated fields on write and decrypt them on read. The `encryptor`
+is any object satisfying the `FieldEncryptor` interface
+(`encryptEntity`/`decryptEntity`) — the framework's data-policy `FieldEncryptor`
+qualifies:
+
+```ts
+class SecureUserRepo extends StreetPostgresRepository<User> {
+  protected readonly tableName = 'users';
+  protected readonly encryptor = myFieldEncryptor;
+  protected readonly encryptedEntity = User;
+  protected mapRow(row) { /* ... */ }
+}
+```
+
+## API
+
+| Member | Description |
+| ------ | ----------- |
+| `findById(id)` | Row by id, or `null`. |
+| `findAll(limit?, offset?)` | Paginated rows (`ORDER BY created_at DESC`). |
+| `create(data)` | Insert non-`undefined` fields, return the row. |
+| `update(id, data)` | Patch fields; empty patch is a no-op read. |
+| `delete(id)` | `true` if a row was deleted. |
+| `count()` | Row count. |
+| `withTransaction(fn)` | Run `fn(conn)` in a transaction. |
+| `streamAll(sql, params?)` | Stream rows (non-parameterized only, for now). |
+
+## Example
+
+A complete runnable example lives in
+[`src/examples/integration.ts`](./src/examples/integration.ts):
+
+```bash
+npm run example -w packages/repository
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @streetjs/repository — the StreetJS generic PostgreSQL repository.
+ *
+ * `StreetPostgresRepository<T>` is a typed CRUD base class over `@streetjs/pool`
+ * with safe identifier validation, pagination, streaming, transactions, and
+ * optional transparent field-level encryption. `LedgerTransactionService` runs a
+ * sequence of operations atomically. Public API only.
+ *
+ * ```ts
+ * import { StreetPostgresRepository } from '@streetjs/repository';
+ *
+ * class UserRepository extends StreetPostgresRepository<User> {
+ *   protected readonly tableName = 'users';
+ *   protected mapRow(row): User { return { id: row.id!, name: row.name! }; }
+ * }
+ * const users = new UserRepository(pool);
+ * await users.findById('42');
+ * ```
+ *
+ * > This is the standalone home of the repository that also backs the
+ * > `streetjs/repository` subpath; the `streetjs` framework re-exports it, so
+ * > there is a single implementation.
+ */
+export { StreetPostgresRepository, LedgerTransactionService, } from './repository.js';
+export type { IRepository, FieldEncryptor } from './repository.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @streetjs/repository — the StreetJS generic PostgreSQL repository.
+ *
+ * `StreetPostgresRepository<T>` is a typed CRUD base class over `@streetjs/pool`
+ * with safe identifier validation, pagination, streaming, transactions, and
+ * optional transparent field-level encryption. `LedgerTransactionService` runs a
+ * sequence of operations atomically. Public API only.
+ *
+ * ```ts
+ * import { StreetPostgresRepository } from '@streetjs/repository';
+ *
+ * class UserRepository extends StreetPostgresRepository<User> {
+ *   protected readonly tableName = 'users';
+ *   protected mapRow(row): User { return { id: row.id!, name: row.name! }; }
+ * }
+ * const users = new UserRepository(pool);
+ * await users.findById('42');
+ * ```
+ *
+ * > This is the standalone home of the repository that also backs the
+ * > `streetjs/repository` subpath; the `streetjs` framework re-exports it, so
+ * > there is a single implementation.
+ */
+export { StreetPostgresRepository, LedgerTransactionService, } from './repository.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,iBAAiB,CAAC"}

package/dist/repository.d.ts

@@ -0,0 +1,58 @@
+import { PgPool } from '@streetjs/pool';
+import type { PgConnection, StreetPostgresWireStream } from '@streetjs/postgres';
+export interface IRepository<T> {
+    findById(id: string): Promise<T | null>;
+    findAll(limit: number, offset: number): Promise<T[]>;
+    create(data: Partial<T>): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<T | null>;
+    delete(id: string): Promise<boolean>;
+    count(): Promise<number>;
+}
+/**
+ * Minimal structural interface for transparent field-level encryption. The
+ * framework's `FieldEncryptor` (in `@streetjs/*` enterprise data-policy) satisfies
+ * it; declaring it structurally keeps this package free of a data-policy
+ * dependency while preserving the optional-encryption feature.
+ */
+export interface FieldEncryptor {
+    encryptEntity<T extends Record<string, unknown>>(entityClass: new (...a: never[]) => unknown, obj: T): T;
+    decryptEntity<T extends Record<string, unknown>>(entityClass: new (...a: never[]) => unknown, obj: T): T;
+}
+export declare abstract class StreetPostgresRepository<T extends object> implements IRepository<T> {
+    protected readonly pool: PgPool;
+    protected abstract readonly tableName: string;
+    constructor(pool: PgPool);
+    /** Validate tableName on first use (abstract property not available in constructor) */
+    private _assertSafeTableName;
+    protected abstract mapRow(row: Record<string, string | null>): T;
+    /**
+     * Optional transparent field-level encryption. Subclasses that set both
+     * `encryptor` and `encryptedEntity` get automatic AES-256-GCM encryption of
+     * `@Encrypt()`-annotated fields on `create()`/`update()` and decryption on
+     * `findById()`/`findAll()`. Defaults to undefined (no encryption).
+     */
+    protected readonly encryptor?: FieldEncryptor;
+    protected readonly encryptedEntity?: new (...a: never[]) => unknown;
+    private _encrypt;
+    private _decrypt;
+    findById(id: string): Promise<T | null>;
+    findAll(limit?: number, offset?: number): Promise<T[]>;
+    count(): Promise<number>;
+    create(data: Partial<T>): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<T | null>;
+    delete(id: string): Promise<boolean>;
+    /** Execute raw SQL within a transaction */
+    withTransaction<R>(fn: (conn: PgConnection) => Promise<R>): Promise<R>;
+    /** Stream rows with backpressure.
+     * Finding 6 fix: accepts parameterized queries only — raw SQL without
+     * params is still possible but callers should always use $1..$N placeholders.
+     * The method signature now accepts params to discourage raw interpolation.
+     */
+    streamAll(sql: string, params?: unknown[]): Promise<StreetPostgresWireStream>;
+}
+export declare class LedgerTransactionService {
+    private readonly pool;
+    constructor(pool: PgPool);
+    execute<T>(operations: Array<(conn: PgConnection) => Promise<void>>, onSuccess?: () => Promise<T>): Promise<T | void>;
+}
+//# sourceMappingURL=repository.d.ts.map

package/dist/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../src/repository.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAIjF,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACrD,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7C,WAAW,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,OAAO,EAC3C,GAAG,EAAE,CAAC,GACL,CAAC,CAAC;IACL,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7C,WAAW,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,OAAO,EAC3C,GAAG,EAAE,CAAC,GACL,CAAC,CAAC;CACN;AAOD,8BAAsB,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAC7D,YAAW,WAAW,CAAC,CAAC,CAAC;IAIb,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAF3C,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,IAAI,EAAE,MAAM;IAO3C,uFAAuF;IACvF,OAAO,CAAC,oBAAoB;IAS5B,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC;IAEhE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC9C,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;IAEpE,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,QAAQ;IAKV,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAUvC,OAAO,CAAC,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAW7C,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAMxB,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAgBpC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAgBvD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS1C,2CAA2C;IACrC,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI5E;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,wBAAwB,CAAC;CAQ9E;AAID,qBAAa,wBAAwB;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,MAAM;IAEnC,OAAO,CAAC,CAAC,EACb,UAAU,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,EACxD,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CASrB"}

package/dist/repository.js

@@ -0,0 +1,127 @@
+// src/repository.ts
+// Generic repository with typed CRUD, safe identifiers, streaming, transactions,
+// and optional transparent field-level encryption.
+// ─── Base repository ────────────────────────────────────────────────────────────
+// Finding 6 fix: safe table/schema name pattern
+const SAFE_TABLE_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;
+export class StreetPostgresRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+        // Finding 6 fix: validate tableName at construction time so a bad subclass
+        // fails immediately rather than silently injecting SQL at query time.
+        // We defer the check to the first query because abstract properties are
+        // not yet initialised in the base constructor — use a lazy validator instead.
+    }
+    /** Validate tableName on first use (abstract property not available in constructor) */
+    _assertSafeTableName() {
+        if (!SAFE_TABLE_NAME_RE.test(this.tableName)) {
+            throw new Error(`Repository tableName contains unsafe characters: "${this.tableName}". ` +
+                'Only letters, digits, underscores, and dots are allowed.');
+        }
+    }
+    /**
+     * Optional transparent field-level encryption. Subclasses that set both
+     * `encryptor` and `encryptedEntity` get automatic AES-256-GCM encryption of
+     * `@Encrypt()`-annotated fields on `create()`/`update()` and decryption on
+     * `findById()`/`findAll()`. Defaults to undefined (no encryption).
+     */
+    encryptor;
+    encryptedEntity;
+    _encrypt(data) {
+        if (!this.encryptor || !this.encryptedEntity)
+            return data;
+        return this.encryptor.encryptEntity(this.encryptedEntity, data);
+    }
+    _decrypt(entity) {
+        if (!this.encryptor || !this.encryptedEntity)
+            return entity;
+        return this.encryptor.decryptEntity(this.encryptedEntity, entity);
+    }
+    async findById(id) {
+        this._assertSafeTableName();
+        const result = await this.pool.query(`SELECT * FROM ${this.tableName} WHERE id = $1 LIMIT 1`, [id]);
+        if (result.rows.length === 0)
+            return null;
+        return this._decrypt(this.mapRow(result.rows[0]));
+    }
+    async findAll(limit = 20, offset = 0) {
+        this._assertSafeTableName();
+        const safeLimit = Math.min(Math.max(1, Math.floor(limit)), 1000);
+        const safeOffset = Math.max(0, Math.floor(offset));
+        const result = await this.pool.query(`SELECT * FROM ${this.tableName} ORDER BY created_at DESC LIMIT $1 OFFSET $2`, [safeLimit, safeOffset]);
+        return result.rows.map((r) => this._decrypt(this.mapRow(r)));
+    }
+    async count() {
+        this._assertSafeTableName();
+        const result = await this.pool.query(`SELECT COUNT(*) AS total FROM ${this.tableName}`);
+        return parseInt(result.rows[0]?.['total'] ?? '0', 10);
+    }
+    async create(data) {
+        this._assertSafeTableName();
+        data = this._encrypt(data);
+        const keys = Object.keys(data).filter((k) => data[k] !== undefined);
+        const columns = keys.map((k) => `"${k}"`).join(', ');
+        const placeholders = keys.map((_, i) => `$${i + 1}`).join(', ');
+        const params = keys.map((k) => data[k]);
+        const result = await this.pool.query(`INSERT INTO ${this.tableName} (${columns}) VALUES (${placeholders}) RETURNING *`, params);
+        const row = result.rows[0];
+        if (!row)
+            throw new Error('Insert returned no rows');
+        return this._decrypt(this.mapRow(row));
+    }
+    async update(id, data) {
+        this._assertSafeTableName();
+        if (Object.keys(data).length === 0)
+            return this.findById(id);
+        data = this._encrypt(data);
+        const entries = Object.entries(data).filter(([, v]) => v !== undefined);
+        const setClauses = entries.map(([k], i) => `"${k}" = $${i + 1}`).join(', ');
+        const params = entries.map(([, v]) => v);
+        params.push(id); // last parameter for WHERE id = $N
+        const result = await this.pool.query(`UPDATE ${this.tableName} SET ${setClauses} WHERE id = $${params.length} RETURNING *`, params);
+        if (result.rows.length === 0)
+            return null;
+        return this._decrypt(this.mapRow(result.rows[0]));
+    }
+    async delete(id) {
+        this._assertSafeTableName();
+        const result = await this.pool.query(`DELETE FROM ${this.tableName} WHERE id = $1`, [id]);
+        return result.command.startsWith('DELETE') && result.rowCount > 0;
+    }
+    /** Execute raw SQL within a transaction */
+    async withTransaction(fn) {
+        return this.pool.transaction(fn);
+    }
+    /** Stream rows with backpressure.
+     * Finding 6 fix: accepts parameterized queries only — raw SQL without
+     * params is still possible but callers should always use $1..$N placeholders.
+     * The method signature now accepts params to discourage raw interpolation.
+     */
+    streamAll(sql, params) {
+        if (params && params.length > 0) {
+            // Note: parameterized streaming requires wire-protocol changes planned for v2.x.
+            // Until then, use non-parameterized SQL for streaming or pool.query() for parameterized queries.
+            throw new Error('streamAll does not yet support parameterized queries — use pool.query() instead');
+        }
+        return this.pool.stream(sql);
+    }
+}
+// ─── ACID ledger service ────────────────────────────────────────────────────────
+export class LedgerTransactionService {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async execute(operations, onSuccess) {
+        return this.pool.transaction(async (conn) => {
+            for (const op of operations) {
+                await op(conn);
+            }
+            if (onSuccess)
+                return onSuccess();
+            return undefined;
+        });
+    }
+}
+//# sourceMappingURL=repository.js.map

package/dist/repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.js","sourceRoot":"","sources":["../src/repository.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@streetjs/repository",
+  "version": "1.0.0",
+  "description": "StreetJS generic PostgreSQL repository: a typed CRUD base class with safe identifier handling, pagination, streaming, transactions, and optional transparent field-level encryption. Built on @streetjs/pool.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map",
+    "!dist/tests/**",
+    "!dist/examples/**",
+    "README.md",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "c8": {
+    "include": ["dist/**/*.js"],
+    "exclude": ["dist/tests/**", "dist/examples/**"],
+    "reporter": ["text", "lcov"],
+    "all": true,
+    "check-coverage": true,
+    "lines": 90,
+    "functions": 90,
+    "branches": 90,
+    "statements": 90
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/tests/*.test.js",
+    "coverage": "c8 node --test dist/tests/*.test.js",
+    "example": "node dist/examples/integration.js",
+    "lint": "tsc --noEmit",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "keywords": [
+    "streetjs",
+    "street-framework",
+    "repository",
+    "crud",
+    "postgresql",
+    "database",
+    "data-access",
+    "field-encryption",
+    "typescript",
+    "esm"
+  ],
+  "author": "street contributors",
+  "license": "MIT",
+  "homepage": "https://hassanmubiru.github.io/StreetJS/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hassanmubiru/StreetJS.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hassanmubiru/StreetJS/issues"
+  },
+  "dependencies": {
+    "@streetjs/pool": "^1.0.0",
+    "@streetjs/postgres": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "c8": "^11.0.0",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}