@nage-api/data 1.0.0-beta.2

package/dist/query/where-matcher.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Evaluate a `Where` clause against a plain object.
+ *
+ * Used by the in-memory driver, and by tests that need to reason about the DSL
+ * without a database. SQL and Mongo drivers translate the same clause into
+ * their own dialect instead — the semantics here are the reference the shared
+ * conformance suite pins down.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesWhere = matchesWhere;
+const LOGICAL_KEYS = new Set(['and', 'or', 'not']);
+/**
+ * Match a SQL `LIKE` pattern: `%` is any run, `_` is a single character, and
+ * every other character is literal.
+ *
+ * This used to translate the pattern into a regular expression, escaping the
+ * metacharacters so a caller could not smuggle one in. Escaping was not the
+ * whole risk: `%` became `.*`, and a pattern with a handful of them backtracked
+ * exponentially, so `{ name: { like: '%%%%%%%%%%%%X' } }` — a client-supplied
+ * operand on any model exposing the default operator list — pinned the event
+ * loop for minutes on a row value of a few dozen characters.
+ *
+ * Walking the two strings instead is linear in the common case and bounded by
+ * O(pattern × value) in the worst, because only the most recent `%` is ever
+ * reconsidered. Building no regular expression also leaves no escaping to get
+ * wrong.
+ */
+function matchesLike(value, pattern) {
+    let valueIndex = 0;
+    let patternIndex = 0;
+    // Where to resume from if the greedy `%` turns out to have eaten too much.
+    let wildcardIndex = -1;
+    let resumeIndex = 0;
+    while (valueIndex < value.length) {
+        const patternChar = patternIndex < pattern.length ? pattern[patternIndex] : undefined;
+        // `%` is tested before the literal comparison on purpose: a value that
+        // itself contains a percent sign must not consume the wildcard as a literal.
+        if (patternChar === '%') {
+            wildcardIndex = patternIndex;
+            resumeIndex = valueIndex;
+            patternIndex += 1;
+            continue;
+        }
+        if (patternChar === '_' || (patternChar !== undefined && patternChar === value[valueIndex])) {
+            valueIndex += 1;
+            patternIndex += 1;
+            continue;
+        }
+        if (wildcardIndex === -1)
+            return false;
+        resumeIndex += 1;
+        valueIndex = resumeIndex;
+        patternIndex = wildcardIndex + 1;
+    }
+    while (patternIndex < pattern.length && pattern[patternIndex] === '%')
+        patternIndex += 1;
+    // The whole value has to be consumed: `like: 'Ham'` does not match 'Hammer'.
+    return patternIndex === pattern.length;
+}
+function compare(actual, operator, operand) {
+    switch (operator) {
+        case 'eq':
+            return actual === operand;
+        case 'ne':
+            return actual !== operand;
+        case 'gt':
+            return isComparable(actual, operand) && actual > operand;
+        case 'gte':
+            return isComparable(actual, operand) && actual >= operand;
+        case 'lt':
+            return isComparable(actual, operand) && actual < operand;
+        case 'lte':
+            return isComparable(actual, operand) && actual <= operand;
+        case 'in':
+            return Array.isArray(operand) && operand.includes(actual);
+        case 'nin':
+            return Array.isArray(operand) && !operand.includes(actual);
+        case 'like':
+            return typeof actual === 'string' && typeof operand === 'string'
+                ? matchesLike(actual, operand)
+                : false;
+        case 'ilike':
+            return typeof actual === 'string' && typeof operand === 'string'
+                ? matchesLike(actual.toLowerCase(), operand.toLowerCase())
+                : false;
+        case 'between':
+            return (Array.isArray(operand) &&
+                operand.length === 2 &&
+                isComparable(actual, operand[0]) &&
+                isComparable(actual, operand[1]) &&
+                actual >= operand[0] &&
+                actual <= operand[1]);
+        case 'isNull':
+            return operand === true ? actual === null || actual === undefined : actual != null;
+        default:
+            return false;
+    }
+}
+/** Both operands are the same ordered primitive, so `<`/`>` are meaningful. */
+function isComparable(left, right) {
+    return ((typeof left === 'number' && typeof right === 'number') ||
+        (typeof left === 'string' && typeof right === 'string'));
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Does `record` satisfy `where`? An empty clause matches everything. */
+function matchesWhere(record, where) {
+    if (where === undefined)
+        return true;
+    for (const [key, value] of Object.entries(where)) {
+        if (value === undefined)
+            continue;
+        if (LOGICAL_KEYS.has(key)) {
+            const clauses = (Array.isArray(value) ? value : [value]);
+            if (key === 'and' && !clauses.every((clause) => matchesWhere(record, clause)))
+                return false;
+            if (key === 'or' && !clauses.some((clause) => matchesWhere(record, clause)))
+                return false;
+            if (key === 'not' && clauses.some((clause) => matchesWhere(record, clause)))
+                return false;
+            continue;
+        }
+        const actual = record[key];
+        if (isPlainObject(value)) {
+            for (const [operator, operand] of Object.entries(value)) {
+                if (!compare(actual, operator, operand))
+                    return false;
+            }
+            continue;
+        }
+        // A bare value is shorthand for equality.
+        if (actual !== value)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=where-matcher.js.map

package/dist/service/model.service.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `ModelService<TEntity>` — the retained template-method service (PLAN.md §14.1).
+ *
+ * The legacy `ModelService` was the framework's most productive idea and its
+ * worst typing: `body: any`, `records: any[]`, `payload: any` at the `Job`
+ * boundary defeated the generic it advertised. The shape is kept — a `Job` flows
+ * through `doBefore*` / `doAfter*` hooks around a data-layer call — but every
+ * member is typed against the entity, and the hooks run **inside** the
+ * transaction so a failing `doAfterCreate` rolls the write back.
+ *
+ * Ownership scoping (`doBeforeRead(job) { job.query.where.user_id = job.owner.id }`)
+ * is first-class rather than a documented convention: `scopeToOwner()` does it
+ * with types.
+ */
+import type { DeepPartial, Id, Job, Paginated, Query, RepositoryPort, UnitOfWork } from '@nage-api/contracts';
+import { NotFoundError } from '@nage-api/core';
+export interface ModelServiceOptions {
+    /** Runs each mutating operation and its hooks atomically. */
+    readonly unitOfWork?: UnitOfWork;
+}
+/**
+ * Base class for a model's service layer.
+ *
+ * Subclasses override only the hooks they need; every hook defaults to a no-op.
+ */
+export declare abstract class ModelService<TEntity extends {
+    id: Id;
+}, TBody = DeepPartial<TEntity>> {
+    #private;
+    protected readonly repository: RepositoryPort<TEntity>;
+    private readonly options;
+    constructor(repository: RepositoryPort<TEntity>, options?: ModelServiceOptions);
+    /** Runs before every read (`findAll`, `findOne`, `findById`, `count`). */
+    protected doBeforeRead(_job: Job<TEntity, TBody>): void | Promise<void>;
+    protected doAfterFindAll(_job: Job<TEntity, TBody>): void | Promise<void>;
+    protected doAfterFindOne(_job: Job<TEntity, TBody>): void | Promise<void>;
+    /** Runs before every write; the last chance to reject or amend the body. */
+    protected doBeforeWrite(_job: Job<TEntity, TBody>): void | Promise<void>;
+    protected doBeforeCreate(_job: Job<TEntity, TBody>): void | Promise<void>;
+    /** Runs inside the transaction: throwing here rolls the create back. */
+    protected doAfterCreate(_job: Job<TEntity, TBody>): void | Promise<void>;
+    protected doBeforeUpdate(_job: Job<TEntity, TBody>): void | Promise<void>;
+    protected doAfterUpdate(_job: Job<TEntity, TBody>): void | Promise<void>;
+    protected doBeforeDelete(_job: Job<TEntity, TBody>): void | Promise<void>;
+    protected doAfterDelete(_job: Job<TEntity, TBody>): void | Promise<void>;
+    findAll(query?: Query<TEntity>): Promise<Paginated<TEntity>>;
+    findOne(query?: Query<TEntity>): Promise<TEntity | null>;
+    /**
+     * Read one record by id, honouring read hooks.
+     *
+     * Scoping applies here too: an ownership hook that adds `where.user_id` means
+     * a caller cannot read someone else's record by guessing its id.
+     */
+    findById(id: Id, query?: Query<TEntity>): Promise<TEntity | null>;
+    /** Like `findById`, but a missing record is a `RESOURCE_NOT_FOUND`. */
+    findByIdOrFail(id: Id, query?: Query<TEntity>): Promise<TEntity>;
+    count(query?: Query<TEntity>): Promise<number>;
+    create(body: TBody): Promise<TEntity>;
+    update(id: Id, body: TBody): Promise<TEntity>;
+    delete(id: Id, mode?: 'soft' | 'hard'): Promise<void>;
+    restore(id: Id): Promise<TEntity>;
+    /**
+     * Constrain a job's query to the records its owner may see — the pattern the
+     * legacy docs described as `job.where.user_id = job.owner.id`, typed.
+     */
+    protected scopeToOwner(job: Job<TEntity, TBody>, field: keyof TEntity & string): void;
+    protected notFound(id: Id): NotFoundError;
+}
+//# sourceMappingURL=model.service.d.ts.map

package/dist/service/model.service.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * `ModelService<TEntity>` — the retained template-method service (PLAN.md §14.1).
+ *
+ * The legacy `ModelService` was the framework's most productive idea and its
+ * worst typing: `body: any`, `records: any[]`, `payload: any` at the `Job`
+ * boundary defeated the generic it advertised. The shape is kept — a `Job` flows
+ * through `doBefore*` / `doAfter*` hooks around a data-layer call — but every
+ * member is typed against the entity, and the hooks run **inside** the
+ * transaction so a failing `doAfterCreate` rolls the write back.
+ *
+ * Ownership scoping (`doBeforeRead(job) { job.query.where.user_id = job.owner.id }`)
+ * is first-class rather than a documented convention: `scopeToOwner()` does it
+ * with types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelService = void 0;
+const core_1 = require("@nage-api/core");
+/**
+ * Base class for a model's service layer.
+ *
+ * Subclasses override only the hooks they need; every hook defaults to a no-op.
+ */
+class ModelService {
+    repository;
+    options;
+    constructor(repository, options = {}) {
+        this.repository = repository;
+        this.options = options;
+    }
+    // ── Lifecycle hooks ───────────────────────────────────────────────────────
+    // Read hooks shape the query before it runs; write hooks see the record after.
+    /** Runs before every read (`findAll`, `findOne`, `findById`, `count`). */
+    doBeforeRead(_job) {
+        return undefined;
+    }
+    doAfterFindAll(_job) {
+        return undefined;
+    }
+    doAfterFindOne(_job) {
+        return undefined;
+    }
+    /** Runs before every write; the last chance to reject or amend the body. */
+    doBeforeWrite(_job) {
+        return undefined;
+    }
+    doBeforeCreate(_job) {
+        return undefined;
+    }
+    /** Runs inside the transaction: throwing here rolls the create back. */
+    doAfterCreate(_job) {
+        return undefined;
+    }
+    doBeforeUpdate(_job) {
+        return undefined;
+    }
+    doAfterUpdate(_job) {
+        return undefined;
+    }
+    doBeforeDelete(_job) {
+        return undefined;
+    }
+    doAfterDelete(_job) {
+        return undefined;
+    }
+    // ── Operations ────────────────────────────────────────────────────────────
+    async findAll(query = {}) {
+        const job = this.#job('findAll', { query });
+        await this.doBeforeRead(job);
+        const page = await this.repository.findAll(job.query);
+        job.records = [...page.records];
+        job.count = page.pagination.count;
+        await this.doAfterFindAll(job);
+        return { records: job.records, pagination: { ...page.pagination, count: job.count } };
+    }
+    async findOne(query = {}) {
+        const job = this.#job('findOne', { query });
+        await this.doBeforeRead(job);
+        const record = await this.repository.findOne(job.query);
+        if (record === null)
+            return null;
+        job.record = record;
+        await this.doAfterFindOne(job);
+        return job.record;
+    }
+    /**
+     * Read one record by id, honouring read hooks.
+     *
+     * Scoping applies here too: an ownership hook that adds `where.user_id` means
+     * a caller cannot read someone else's record by guessing its id.
+     */
+    async findById(id, query = {}) {
+        const job = this.#job('findById', { query, id });
+        await this.doBeforeRead(job);
+        return this.findOne({ ...job.query, where: withId(job.query.where, id) });
+    }
+    /** Like `findById`, but a missing record is a `RESOURCE_NOT_FOUND`. */
+    async findByIdOrFail(id, query = {}) {
+        const record = await this.findById(id, query);
+        if (record === null)
+            throw this.notFound(id);
+        return record;
+    }
+    async count(query = {}) {
+        const job = this.#job('count', { query });
+        await this.doBeforeRead(job);
+        return this.repository.count(job.query);
+    }
+    async create(body) {
+        const job = this.#job('create', { body });
+        return this.#transactional(async (tx) => {
+            await this.doBeforeWrite(job);
+            await this.doBeforeCreate(job);
+            job.record = await this.repository.create(job.body, tx === undefined ? {} : { tx });
+            await this.doAfterCreate(job);
+            return job.record;
+        });
+    }
+    async update(id, body) {
+        const existing = await this.findById(id);
+        if (existing === null)
+            throw this.notFound(id);
+        const job = this.#job('update', { body, id });
+        job.record = existing;
+        return this.#transactional(async (tx) => {
+            await this.doBeforeWrite(job);
+            await this.doBeforeUpdate(job);
+            job.record = await this.repository.update(id, job.body, tx === undefined ? {} : { tx });
+            await this.doAfterUpdate(job);
+            return job.record;
+        });
+    }
+    async delete(id, mode = 'soft') {
+        const existing = await this.findById(id);
+        if (existing === null)
+            throw this.notFound(id);
+        const job = this.#job('delete', { id, deleteMode: mode });
+        job.record = existing;
+        await this.#transactional(async (tx) => {
+            await this.doBeforeDelete(job);
+            await this.repository.delete(id, tx === undefined ? { mode } : { mode, tx });
+            await this.doAfterDelete(job);
+            return undefined;
+        });
+    }
+    async restore(id) {
+        return this.#transactional(async (tx) => this.repository.restore(id, tx === undefined ? {} : { tx }));
+    }
+    // ── Helpers for subclasses ────────────────────────────────────────────────
+    /**
+     * Constrain a job's query to the records its owner may see — the pattern the
+     * legacy docs described as `job.where.user_id = job.owner.id`, typed.
+     */
+    scopeToOwner(job, field) {
+        const owner = job.owner;
+        if (owner === undefined)
+            return;
+        job.query = {
+            ...job.query,
+            where: { ...job.query.where, [field]: owner.id },
+        };
+    }
+    notFound(id) {
+        return new core_1.NotFoundError({
+            detail: `${this.repository.descriptor.name} ${String(id)} was not found`,
+            meta: { model: this.repository.descriptor.name, id },
+        });
+    }
+    // ── Internals ─────────────────────────────────────────────────────────────
+    #job(action, input) {
+        return (0, core_1.createJob)({
+            action,
+            ...(input.query === undefined ? {} : { query: input.query }),
+            ...(input.body === undefined ? {} : { body: input.body }),
+            ...(input.id === undefined ? {} : { id: input.id }),
+            ...(input.deleteMode === undefined ? {} : { deleteMode: input.deleteMode }),
+        });
+    }
+    /** Run `fn` in a transaction when one is available, directly otherwise. */
+    async #transactional(fn) {
+        const unitOfWork = this.options.unitOfWork;
+        if (unitOfWork === undefined)
+            return fn(undefined);
+        return unitOfWork.run(async (tx) => fn(tx));
+    }
+}
+exports.ModelService = ModelService;
+function withId(where, id) {
+    return { ...where, id };
+}
+//# sourceMappingURL=model.service.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tokens owned by `@nage-api/data`.
+ *
+ * `NAGE_UNIT_OF_WORK` and the per-model repository tokens are declared by
+ * `@nage-api/core`, since a feature package injecting a repository must not have to
+ * depend on the data package to name it.
+ */
+import { type Token } from '@nage-api/core';
+import type { DataSourceHealth } from '@nage-api/contracts';
+/** Connection probe published by the active driver (§21). */
+export declare const NAGE_DATA_HEALTH: Token<DataSourceHealth>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Tokens owned by `@nage-api/data`.
+ *
+ * `NAGE_UNIT_OF_WORK` and the per-model repository tokens are declared by
+ * `@nage-api/core`, since a feature package injecting a repository must not have to
+ * depend on the data package to name it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_DATA_HEALTH = void 0;
+const core_1 = require("@nage-api/core");
+/** Connection probe published by the active driver (§21). */
+exports.NAGE_DATA_HEALTH = (0, core_1.createToken)('NAGE_DATA_HEALTH');
+//# sourceMappingURL=tokens.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nage-api/data",
+  "version": "1.0.0-beta.2",
+  "description": "Engine-agnostic data layer for @nage-api — repository contract, typed query DSL, ModelService, migrations",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/testing": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10",
+    "@nage-api/testing": "1.0.0-beta.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}