@opengroundplan/core 0.1.1

package/templates/layers/db-core/files/src/__solutionName.snake__/db/memory.py

@@ -0,0 +1,143 @@
+"""In-memory adapter.
+
+Exists so the project runs and tests before an engine layer is installed. Not for
+production: transactions are serialized behind one lock and state dies with the process.
+"""
+
+import asyncio
+import copy
+from typing import Any, Awaitable, Callable, TypeVar
+
+from .errors import DbError
+from .ports import Criteria, Page, Sort, UnitOfWork
+
+R = TypeVar("R")
+
+Rows = dict[Any, Any]
+Store = dict[str, Rows]
+
+
+def _snapshot(store: Store) -> Store:
+    return {collection: dict(rows) for collection, rows in store.items()}
+
+
+def _matches(row: Any, where: dict[str, Any] | None) -> bool:
+    if not where:
+        return True
+    return all(getattr(row, key, None) == value for key, value in where.items())
+
+
+class MemoryRepository:
+    def __init__(self, collection: str, rows_of: Callable[[str], Rows]) -> None:
+        self._collection = collection
+        self._rows_of = rows_of
+
+    @property
+    def _rows(self) -> Rows:
+        return self._rows_of(self._collection)
+
+    async def find_by_id(self, entity_id: Any) -> Any | None:
+        row = self._rows.get(entity_id)
+        return copy.deepcopy(row) if row is not None else None
+
+    async def find(self, criteria: Criteria | None = None) -> list[Any]:
+        criteria = criteria or Criteria()
+        found = self._select(criteria)
+        end = None if criteria.limit is None else criteria.offset + criteria.limit
+        return found[criteria.offset : end]
+
+    async def page(self, criteria: Criteria | None = None) -> Page[Any]:
+        criteria = criteria or Criteria()
+        found = self._select(criteria)
+        limit = len(found) if criteria.limit is None else criteria.limit
+        return Page(
+            items=found[criteria.offset : criteria.offset + limit],
+            total=len(found),
+            limit=limit,
+            offset=criteria.offset,
+        )
+
+    async def count(self, where: dict[str, Any] | None = None) -> int:
+        return len(self._select(Criteria(where=where)))
+
+    async def add(self, entity: Any) -> Any:
+        entity_id = entity.id
+        if entity_id in self._rows:
+            raise DbError.conflict(self._collection, entity_id)
+        self._rows[entity_id] = copy.deepcopy(entity)
+        return copy.deepcopy(entity)
+
+    async def update(self, entity: Any) -> Any:
+        entity_id = entity.id
+        if entity_id not in self._rows:
+            raise DbError.not_found(self._collection, entity_id)
+        self._rows[entity_id] = copy.deepcopy(entity)
+        return copy.deepcopy(entity)
+
+    async def remove(self, entity_id: Any) -> bool:
+        return self._rows.pop(entity_id, None) is not None
+
+    def _select(self, criteria: Criteria) -> list[Any]:
+        found = [copy.deepcopy(row) for row in self._rows.values() if _matches(row, criteria.where)]
+        for rule in reversed(criteria.sort):
+            found.sort(key=_sort_key(rule), reverse=rule.direction == "desc")
+        return found
+
+
+def _sort_key(rule: Sort) -> Callable[[Any], Any]:
+    # Missing attributes sort first rather than raising mid-query.
+    return lambda row: (getattr(row, rule.field, None) is not None, getattr(row, rule.field, None))
+
+
+class MemoryUnitOfWork:
+    def __init__(self, working: Store, on_commit: Callable[[Store], None]) -> None:
+        self._working = working
+        self._on_commit = on_commit
+        self._settled = False
+
+    def repository(self, collection: str) -> MemoryRepository:
+        return MemoryRepository(collection, lambda name: self._working.setdefault(name, {}))
+
+    async def commit(self) -> None:
+        self._assert_open()
+        self._settled = True
+        self._on_commit(self._working)
+
+    async def rollback(self) -> None:
+        self._assert_open()
+        self._settled = True
+        self._working = {}
+
+    def _assert_open(self) -> None:
+        if self._settled:
+            raise DbError("conflict", "unit of work already committed or rolled back")
+
+
+class MemoryDatabase:
+    def __init__(self) -> None:
+        self._committed: Store = {}
+        self._lock = asyncio.Lock()
+        self._closed = False
+
+    async def transaction(self, work: Callable[[UnitOfWork], Awaitable[R]]) -> R:
+        async with self._lock:
+            if self._closed:
+                raise DbError("unavailable", "database is closed")
+            uow = MemoryUnitOfWork(_snapshot(self._committed), self._replace)
+            try:
+                result = await work(uow)
+            except Exception as error:  # cancellation must propagate untouched
+                await uow.rollback()
+                raise DbError.wrap("unknown", error) from error
+            await uow.commit()
+            return result
+
+    async def ping(self) -> bool:
+        return not self._closed
+
+    async def close(self) -> None:
+        self._closed = True
+        self._committed = {}
+
+    def _replace(self, store: Store) -> None:
+        self._committed = store

package/templates/layers/db-core/files/src/__solutionName.snake__/db/ports.py

@@ -0,0 +1,80 @@
+"""Engine-neutral persistence ports.
+
+Application code depends on this module only; db-postgres, db-mongo and friends supply
+the implementations.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Generic, Literal, Protocol, TypeVar
+
+T = TypeVar("T")
+TId = TypeVar("TId")
+R = TypeVar("R")
+
+SortDirection = Literal["asc", "desc"]
+
+
+class Entity(Protocol):
+    """Anything with an ``id`` attribute."""
+
+    id: Any
+
+
+@dataclass(frozen=True, slots=True)
+class Sort:
+    field: str
+    direction: SortDirection = "asc"
+
+
+@dataclass(frozen=True, slots=True)
+class Criteria:
+    """Equality, ordering and slicing — what every engine can express natively."""
+
+    where: dict[str, Any] | None = None
+    sort: tuple[Sort, ...] = ()
+    limit: int | None = None
+    offset: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class Page(Generic[T]):
+    items: list[T]
+    total: int
+    limit: int
+    offset: int
+
+
+class Repository(Protocol[T, TId]):
+    async def find_by_id(self, entity_id: TId) -> T | None: ...
+
+    async def find(self, criteria: Criteria | None = None) -> list[T]: ...
+
+    async def page(self, criteria: Criteria | None = None) -> Page[T]: ...
+
+    async def count(self, where: dict[str, Any] | None = None) -> int: ...
+
+    async def add(self, entity: T) -> T: ...
+
+    async def update(self, entity: T) -> T: ...
+
+    async def remove(self, entity_id: TId) -> bool: ...
+
+
+class UnitOfWork(Protocol):
+    """One transactional scope. Repositories from the same unit share its transaction."""
+
+    def repository(self, collection: str) -> Repository[Any, Any]: ...
+
+    async def commit(self) -> None: ...
+
+    async def rollback(self) -> None: ...
+
+
+class Database(Protocol):
+    async def transaction(self, work: Callable[[UnitOfWork], Awaitable[R]]) -> R:
+        """Commits when ``work`` returns, rolls back when it raises."""
+        ...
+
+    async def ping(self) -> bool: ...
+
+    async def close(self) -> None: ...

package/templates/layers/db-core/files/src/__solutionName.snake__/db/retry.py

@@ -0,0 +1,25 @@
+"""Retry for transient faults only. Attempts and backoff come from config, never a call site."""
+
+import asyncio
+from typing import Awaitable, Callable, TypeVar
+
+from .config import db_config
+from .errors import is_retryable
+
+R = TypeVar("R")
+
+
+async def with_retry(work: Callable[[], Awaitable[R]]) -> R:
+    last: Exception | None = None
+
+    for attempt in range(db_config.max_tx_retries + 1):
+        try:
+            return await work()
+        except Exception as error:
+            last = error
+            if not is_retryable(error) or attempt == db_config.max_tx_retries:
+                break
+            await asyncio.sleep(db_config.retry_base_delay_ms * (2**attempt) / 1000)
+
+    assert last is not None
+    raise last

package/templates/layers/db-core/files/src/db/config.ts

@@ -0,0 +1,65 @@
+/**
+ * The only place database settings are read. Nothing else in the app touches
+ * process.env for persistence — engine layers extend this table, they do not bypass it.
+ */
+
+const PREFIX = '{{ dbEnvPrefix }}';
+
+export interface DbConfig {
+  /** Empty means no engine layer is installed; the in-memory adapter takes over. */
+  url: string;
+  poolMin: number;
+  poolMax: number;
+  connectTimeoutMs: number;
+  statementTimeoutMs: number;
+  /** Retries apply only to errors the taxonomy marks retryable. */
+  maxTxRetries: number;
+  retryBaseDelayMs: number;
+  logQueries: boolean;
+}
+
+/** Typed defaults. The single place a literal database value may appear. */
+const defaults: DbConfig = {
+  url: '',
+  poolMin: 1,
+  poolMax: 10,
+  connectTimeoutMs: 10_000,
+  statementTimeoutMs: 30_000,
+  maxTxRetries: 3,
+  retryBaseDelayMs: 50,
+  logQueries: false,
+};
+
+function raw(key: string): string | undefined {
+  const value = process.env[`${PREFIX}_${key}`];
+  return value === undefined || value === '' ? undefined : value;
+}
+
+function int(key: string, fallback: number): number {
+  const value = raw(key);
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  // Fail at startup rather than pass NaN to a driver.
+  if (!Number.isInteger(parsed)) throw new Error(`${PREFIX}_${key} must be an integer, got "${value}"`);
+  return parsed;
+}
+
+function bool(key: string, fallback: boolean): boolean {
+  const value = raw(key)?.toLowerCase();
+  if (value === undefined) return fallback;
+  return value === '1' || value === 'true' || value === 'yes';
+}
+
+export const dbConfig: DbConfig = {
+  url: raw('URL') ?? defaults.url,
+  poolMin: int('POOL_MIN', defaults.poolMin),
+  poolMax: int('POOL_MAX', defaults.poolMax),
+  connectTimeoutMs: int('CONNECT_TIMEOUT_MS', defaults.connectTimeoutMs),
+  statementTimeoutMs: int('STATEMENT_TIMEOUT_MS', defaults.statementTimeoutMs),
+  maxTxRetries: int('MAX_TX_RETRIES', defaults.maxTxRetries),
+  retryBaseDelayMs: int('RETRY_BASE_DELAY_MS', defaults.retryBaseDelayMs),
+  logQueries: bool('LOG_QUERIES', defaults.logQueries),
+};
+
+/** False until an engine layer supplies a connection URL. */
+export const hasEngine = dbConfig.url.length > 0;

package/templates/layers/db-core/files/src/db/errors.ts

@@ -0,0 +1,52 @@
+/**
+ * One error taxonomy for every engine. Drivers leak vendor error codes; engine layers
+ * translate them here so callers can branch on intent without importing a driver.
+ */
+
+export type DbErrorKind =
+  | 'not-found'
+  | 'conflict'
+  | 'integrity'
+  | 'timeout'
+  | 'transient'
+  | 'unavailable'
+  | 'unknown';
+
+const RETRYABLE: ReadonlySet<DbErrorKind> = new Set<DbErrorKind>([
+  'timeout',
+  'transient',
+  'unavailable',
+]);
+
+export class DbError extends Error {
+  constructor(
+    readonly kind: DbErrorKind,
+    message: string,
+    readonly detail?: unknown,
+  ) {
+    super(message);
+    this.name = 'DbError';
+  }
+
+  /** Drives the retry helper — a conflict must never be retried blindly. */
+  get retryable(): boolean {
+    return RETRYABLE.has(this.kind);
+  }
+
+  static notFound(collection: string, id: unknown): DbError {
+    return new DbError('not-found', `${collection}: no row with id ${String(id)}`);
+  }
+
+  static conflict(collection: string, id: unknown): DbError {
+    return new DbError('conflict', `${collection}: id ${String(id)} already exists`);
+  }
+
+  static from(kind: DbErrorKind, error: unknown): DbError {
+    if (error instanceof DbError) return error;
+    return new DbError(kind, error instanceof Error ? error.message : String(error), error);
+  }
+}
+
+export function isRetryable(error: unknown): boolean {
+  return error instanceof DbError && error.retryable;
+}

package/templates/layers/db-core/files/src/db/index.ts

@@ -0,0 +1,41 @@
+/**
+ * The swap point. Application code imports `database()`; an engine layer calls
+ * `useDatabase()` once at startup. Until one does, the in-memory adapter keeps the app runnable.
+ */
+import { MemoryDatabase } from './memory.js';
+import type { Database } from './ports.js';
+
+export { dbConfig, hasEngine, type DbConfig } from './config.js';
+export { DbError, isRetryable, type DbErrorKind } from './errors.js';
+export { withRetry } from './retry.js';
+export { MemoryDatabase } from './memory.js';
+export type {
+  Criteria,
+  Database,
+  Entity,
+  EntityId,
+  Page,
+  Repository,
+  Sort,
+  SortDirection,
+  UnitOfWork,
+} from './ports.js';
+
+let factory: () => Database = () => new MemoryDatabase();
+let instance: Database | null = null;
+
+export function useDatabase(next: () => Database): void {
+  factory = next;
+  instance = null;
+}
+
+export function database(): Database {
+  instance ??= factory();
+  return instance;
+}
+
+/** Drops the cached instance — call between tests, or after config changes. */
+export async function resetDatabase(): Promise<void> {
+  await instance?.close();
+  instance = null;
+}

package/templates/layers/db-core/files/src/db/memory.test.ts

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { DbError } from './errors.js';
+import { MemoryDatabase } from './memory.js';
+import { database, resetDatabase, useDatabase } from './index.js';
+import type { Entity } from './ports.js';
+
+interface User extends Entity {
+  readonly id: string;
+  name: string;
+  age: number;
+}
+
+const COLLECTION = 'users';
+
+// Tuple, not User[] — indexing a fixture must stay provably defined under strict tsconfigs.
+const users: [User, User, User] = [
+  { id: 'a', name: 'Ada', age: 36 },
+  { id: 'b', name: 'Linus', age: 28 },
+  { id: 'c', name: 'Grace', age: 45 },
+];
+
+async function seed(db: MemoryDatabase): Promise<void> {
+  await db.transaction(async (uow) => {
+    const repo = uow.repository<User>(COLLECTION);
+    for (const user of users) await repo.add(user);
+  });
+}
+
+describe('memory repository', () => {
+  let db: MemoryDatabase;
+
+  beforeEach(async () => {
+    db = new MemoryDatabase();
+    await seed(db);
+  });
+
+  it('reads back what it wrote', async () => {
+    const found = await db.transaction((uow) => uow.repository<User>(COLLECTION).findById('a'));
+    expect(found?.name).toBe('Ada');
+  });
+
+  it('returns null rather than throwing for a missing id', async () => {
+    const found = await db.transaction((uow) => uow.repository<User>(COLLECTION).findById('zz'));
+    expect(found).toBeNull();
+  });
+
+  it('filters, sorts and pages', async () => {
+    const page = await db.transaction((uow) =>
+      uow.repository<User>(COLLECTION).page({ sort: [{ field: 'age', direction: 'desc' }], limit: 2 }),
+    );
+    expect(page.items.map((u) => u.name)).toEqual(['Grace', 'Ada']);
+    expect(page.total).toBe(3);
+  });
+
+  it('counts by equality criteria', async () => {
+    const count = await db.transaction((uow) =>
+      uow.repository<User>(COLLECTION).count({ where: { name: 'Ada' } }),
+    );
+    expect(count).toBe(1);
+  });
+
+  it('rejects a duplicate id as a conflict', async () => {
+    await expect(
+      db.transaction((uow) => uow.repository<User>(COLLECTION).add(users[0])),
+    ).rejects.toMatchObject({ kind: 'conflict' });
+  });
+
+  it('rolls the whole unit back when the work throws', async () => {
+    await expect(
+      db.transaction(async (uow) => {
+        const repo = uow.repository<User>(COLLECTION);
+        await repo.remove('a');
+        throw new Error('boom');
+      }),
+    ).rejects.toThrow('boom');
+
+    const survivors = await db.transaction((uow) => uow.repository<User>(COLLECTION).count());
+    expect(survivors).toBe(3);
+  });
+
+  it('does not let a caller mutate stored state through a returned entity', async () => {
+    const found = await db.transaction((uow) => uow.repository<User>(COLLECTION).findById('a'));
+    found!.name = 'tampered';
+    const again = await db.transaction((uow) => uow.repository<User>(COLLECTION).findById('a'));
+    expect(again?.name).toBe('Ada');
+  });
+});
+
+describe('error taxonomy', () => {
+  it('marks only transient kinds retryable', () => {
+    expect(new DbError('transient', 'x').retryable).toBe(true);
+    expect(new DbError('timeout', 'x').retryable).toBe(true);
+    expect(new DbError('conflict', 'x').retryable).toBe(false);
+    expect(new DbError('not-found', 'x').retryable).toBe(false);
+  });
+});
+
+describe('database registration', () => {
+  it('hands back the engine an adapter registered, not the default', async () => {
+    await resetDatabase();
+    const engine = new MemoryDatabase();
+    useDatabase(() => engine);
+    expect(database()).toBe(engine);
+    await resetDatabase();
+    useDatabase(() => new MemoryDatabase());
+  });
+});

package/templates/layers/db-core/files/src/db/memory.ts

@@ -0,0 +1,182 @@
+/**
+ * In-memory adapter. It exists so the repo builds, tests and runs before an engine layer
+ * is installed — and so unit tests never need a live database. Not for production:
+ * transactions are serialized and state dies with the process.
+ */
+import { DbError } from './errors.js';
+import type { Criteria, Database, Entity, EntityId, Page, Repository, UnitOfWork } from './ports.js';
+
+type Rows = Map<EntityId, Record<string, unknown>>;
+type Store = Map<string, Rows>;
+
+function snapshot(store: Store): Store {
+  const copy: Store = new Map();
+  for (const [collection, rows] of store) copy.set(collection, new Map(rows));
+  return copy;
+}
+
+/** Entities are copied in and out so a caller's mutation cannot reach stored state. */
+function clone<T>(value: T): T {
+  return { ...(value as Record<string, unknown>) } as T;
+}
+
+function matches(row: Record<string, unknown>, where: Record<string, unknown> | undefined): boolean {
+  if (!where) return true;
+  return Object.entries(where).every(([key, value]) => row[key] === value);
+}
+
+function compare(a: unknown, b: unknown): number {
+  if (a === b) return 0;
+  if (a === undefined || a === null) return -1;
+  if (b === undefined || b === null) return 1;
+  return a < b ? -1 : 1;
+}
+
+class MemoryRepository<T extends Entity<TId>, TId extends EntityId>
+  implements Repository<T, TId>
+{
+  constructor(
+    private readonly collection: string,
+    private readonly rowsOf: (collection: string) => Rows,
+  ) {}
+
+  private get rows(): Rows {
+    return this.rowsOf(this.collection);
+  }
+
+  findById(id: TId): Promise<T | null> {
+    const row = this.rows.get(id);
+    return Promise.resolve(row ? (clone(row) as T) : null);
+  }
+
+  find(criteria: Criteria<T> = {}): Promise<T[]> {
+    return Promise.resolve(
+      this.select(criteria).slice(
+        criteria.offset ?? 0,
+        criteria.limit === undefined ? undefined : (criteria.offset ?? 0) + criteria.limit,
+      ),
+    );
+  }
+
+  page(criteria: Criteria<T> = {}): Promise<Page<T>> {
+    const all = this.select(criteria);
+    const offset = criteria.offset ?? 0;
+    const limit = criteria.limit ?? all.length;
+    return Promise.resolve({ items: all.slice(offset, offset + limit), total: all.length, limit, offset });
+  }
+
+  count(criteria: Pick<Criteria<T>, 'where'> = {}): Promise<number> {
+    return Promise.resolve(this.select(criteria).length);
+  }
+
+  add(entity: T): Promise<T> {
+    if (this.rows.has(entity.id)) throw DbError.conflict(this.collection, entity.id);
+    this.rows.set(entity.id, clone(entity) as Record<string, unknown>);
+    return Promise.resolve(clone(entity));
+  }
+
+  update(entity: T): Promise<T> {
+    if (!this.rows.has(entity.id)) throw DbError.notFound(this.collection, entity.id);
+    this.rows.set(entity.id, clone(entity) as Record<string, unknown>);
+    return Promise.resolve(clone(entity));
+  }
+
+  remove(id: TId): Promise<boolean> {
+    return Promise.resolve(this.rows.delete(id));
+  }
+
+  private select(criteria: Criteria<T>): T[] {
+    const found = [...this.rows.values()]
+      .filter((row) => matches(row, criteria.where as Record<string, unknown> | undefined))
+      .map((row) => clone(row) as T);
+
+    for (const sort of [...(criteria.sort ?? [])].reverse()) {
+      found.sort((a, b) => {
+        const order = compare(
+          (a as Record<string, unknown>)[sort.field],
+          (b as Record<string, unknown>)[sort.field],
+        );
+        return sort.direction === 'desc' ? -order : order;
+      });
+    }
+    return found;
+  }
+}
+
+class MemoryUnitOfWork implements UnitOfWork {
+  private settled = false;
+
+  constructor(
+    private working: Store,
+    private readonly onCommit: (store: Store) => void,
+  ) {}
+
+  repository<T extends Entity<TId>, TId extends EntityId = string>(
+    collection: string,
+  ): Repository<T, TId> {
+    return new MemoryRepository<T, TId>(collection, (name) => {
+      let rows = this.working.get(name);
+      if (!rows) {
+        rows = new Map();
+        this.working.set(name, rows);
+      }
+      return rows;
+    });
+  }
+
+  commit(): Promise<void> {
+    this.assertOpen();
+    this.settled = true;
+    this.onCommit(this.working);
+    return Promise.resolve();
+  }
+
+  rollback(): Promise<void> {
+    this.assertOpen();
+    this.settled = true;
+    this.working = new Map();
+    return Promise.resolve();
+  }
+
+  private assertOpen(): void {
+    if (this.settled) throw new DbError('conflict', 'unit of work already committed or rolled back');
+  }
+}
+
+export class MemoryDatabase implements Database {
+  private committed: Store = new Map();
+  /** Serializes transactions so a snapshot can stand in for real isolation. */
+  private queue: Promise<unknown> = Promise.resolve();
+  private closed = false;
+
+  async transaction<R>(work: (uow: UnitOfWork) => Promise<R>): Promise<R> {
+    const run = this.queue.then(async () => {
+      if (this.closed) throw new DbError('unavailable', 'database is closed');
+      const uow = new MemoryUnitOfWork(snapshot(this.committed), (store) => {
+        this.committed = store;
+      });
+      try {
+        const result = await work(uow);
+        await uow.commit();
+        return result;
+      } catch (error) {
+        await uow.rollback();
+        throw DbError.from('unknown', error);
+      }
+    });
+
+    // Keep the chain alive after a failed transaction.
+    this.queue = run.catch(() => undefined);
+    return run;
+  }
+
+  ping(): Promise<boolean> {
+    return Promise.resolve(!this.closed);
+  }
+
+  close(): Promise<void> {
+    this.closed = true;
+    this.committed = new Map();
+    return Promise.resolve();
+  }
+}