@quickservicets/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Rauber Pereira
+
+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

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @quickservicets/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The runtime of [QuickService.ts](https://github.com/ricardorauber/quickservicets), a backend framework for [Bun](https://bun.sh): write your entities as TypeScript types in `entities/`, and get CRUD routes, validation, filters, relations, file uploads, migrations and OpenAPI docs on an in-memory, SQLite, PostgreSQL or MongoDB database.
+
+Create a project with the CLI, which adds this package for you:
+
+```bash
+bunx quickservicets init my-api --db sqlite
+```
+
+Documentation and source: https://github.com/ricardorauber/quickservicets
+
+MIT license.

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@quickservicets/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The QuickService.ts runtime: build typed, validated and documented REST APIs on Bun from TypeScript entity types.",
+  "keywords": [
+    "quickservicets",
+    "bun",
+    "typescript",
+    "rest",
+    "api",
+    "backend",
+    "framework",
+    "crud",
+    "openapi"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricardorauber/quickservicets.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/ricardorauber/quickservicets#readme",
+  "bugs": {
+    "url": "https://github.com/ricardorauber/quickservicets/issues"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./testing": "./src/testing/index.ts",
+    "./features/*": "./src/features/*"
+  },
+  "dependencies": {
+    "drizzle-orm": "0.45.4",
+    "mongodb": "7.7.0"
+  },
+  "devDependencies": {
+    "drizzle-kit": "0.31.11"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-support.ts",
+    "!src/**/*-test-support.ts",
+    "!src/**/__snapshots__",
+    "!src/**/fixtures",
+    "!src/**/.generated",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/adapter.ts

@@ -0,0 +1,159 @@
+import type { EntityModel } from "./model.ts";
+import type { Condition, SortField } from "./query.ts";
+
+/** A record as stored by an adapter: the entity fields plus the system fields. */
+export type StoredRecord = Record<string, unknown> & {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+/** Columns a read may skip. */
+export interface ReadColumns {
+  /**
+   * Top-level fields not to read from the database (stored as the entity's own columns); the returned records leave
+   * them out. Adapters that cannot skip columns may return them.
+   */
+  omit?: readonly string[];
+}
+
+export interface FindManyOptions extends ReadColumns {
+  where: Condition[];
+  sort: SortField[];
+  limit: number;
+  offset: number;
+  /** False skips counting the matches; `total` is then the number of records returned (default true). */
+  withTotal?: boolean;
+}
+
+export interface FindManyResult {
+  data: StoredRecord[];
+  total: number;
+}
+
+/**
+ * One aggregate computed by `DatabaseAdapter.aggregate`: the number of matches (only those that also satisfy `where`,
+ * when given), or a function over a number or date field.
+ */
+export type Aggregate =
+  | { fn: "count"; where?: Condition[] }
+  | { fn: "sum" | "avg" | "min" | "max"; field: string };
+
+/** Aggregate results by name: counts are numbers, the others numbers or dates, or null without values. */
+export type AggregateValues = Record<string, number | Date | null>;
+
+/** A reference array, field `field` of `owner`, from which a delete removes the deleted record's id. */
+export interface ReferencePull {
+  owner: EntityModel;
+  field: string;
+}
+
+/**
+ * The records one record references through a reference array: those listed in field `field` of the `owner` record
+ * with id `id`, which are records of `target`.
+ */
+export interface RelatedScope {
+  owner: EntityModel;
+  id: string;
+  field: string;
+  target: EntityModel;
+}
+
+export type AdapterKind = "memory" | "sqlite" | "postgres" | "mongodb";
+
+export interface ConnectOptions {
+  /** The resolved default schema (see `loadConfig`), or null for the database's own default. */
+  defaultSchema?: string | null;
+  /** The server processes sharing the adapter's connection pool size, each opening its share (default 1). */
+  workers?: number;
+}
+
+export interface DatabaseAdapter {
+  /** Identifies built-in adapters, so tools such as migrations know the database dialect. */
+  readonly kind?: AdapterKind;
+  connect(models: EntityModel[], options?: ConnectOptions): Promise<void>;
+  disconnect(): Promise<void>;
+  findById(entity: EntityModel, id: string, options?: ReadColumns): Promise<StoredRecord | null>;
+  findOne(entity: EntityModel, where: Condition[]): Promise<StoredRecord | null>;
+  findMany(entity: EntityModel, options: FindManyOptions): Promise<FindManyResult>;
+  /** Stores a new record and resolves the record as stored. */
+  insert(entity: EntityModel, record: StoredRecord): Promise<StoredRecord>;
+  /**
+   * Updates the record with that id; with `where`, only when the record also matches those conditions, checked in the
+   * same atomic write. Resolves the record as stored after the update, or null when no record was updated.
+   */
+  updateById(entity: EntityModel, id: string, changes: Record<string, unknown>, where?: Condition[]): Promise<StoredRecord | null>;
+  deleteById(entity: EntityModel, id: string): Promise<boolean>;
+  /**
+   * Atomically adds each number of `amounts` to that field of the record with `id` and returns the record; when no
+   * record has that id, inserts `insert` with the amounts as its values (optional). Concurrent calls never lose a count.
+   */
+  increment?(entity: EntityModel, id: string, amounts: Record<string, number>, insert: StoredRecord): Promise<StoredRecord>;
+  /**
+   * Inserts the record unless a stored record has the same value of its unique field `unique`, resolving null then;
+   * a conflict never fails the current transaction, and a conflicting insert of another uncommitted transaction is
+   * waited for (optional; without it, callers insert and catch `UniqueViolationError`).
+   */
+  insertOrSkip?(entity: EntityModel, record: StoredRecord, unique: string): Promise<StoredRecord | null>;
+  /**
+   * Deletes the record with that id and, in the same atomic write, removes its id from the junction-stored reference
+   * arrays `pulls` without rewriting their other items. Every record that held the id gets `updatedAt`, or 1 ms after
+   * its stored `updatedAt` when that is not earlier. Resolves false when no record was deleted. Optional: without it,
+   * a delete rewrites each reference array that held the id.
+   */
+  deleteAndPull?(entity: EntityModel, id: string, pulls: ReferencePull[], updatedAt: Date): Promise<boolean>;
+  count(entity: EntityModel, where: Condition[]): Promise<number>;
+  /**
+   * Computes every aggregate over the records matching `where` in one statement (or pipeline). Counts are 0 and the
+   * other aggregates null when no record has a value.
+   */
+  aggregate(entity: EntityModel, where: Condition[], aggregates: Record<string, Aggregate>): Promise<AggregateValues>;
+  /**
+   * A page of the related records of `scope` matching `where`, like `findMany` on the target entity; no records when
+   * the owner does not exist. Optional, like `countRelated` and `aggregateRelated`: without them, related queries read
+   * the owner's array first and then filter the target by id.
+   */
+  findRelated?(scope: RelatedScope, options: FindManyOptions): Promise<FindManyResult>;
+  /** The number of related records of `scope` matching `where`; 0 when the owner does not exist. */
+  countRelated?(scope: RelatedScope, where: Condition[]): Promise<number>;
+  /**
+   * Every aggregate over the related records of `scope` matching `where`, in one statement on SQL databases. Resolves
+   * null when the owner does not exist; counts are 0 and the other aggregates null when no related record has a value.
+   */
+  aggregateRelated?(scope: RelatedScope, where: Condition[], aggregates: Record<string, Aggregate>): Promise<AggregateValues | null>;
+  /** Runs `fn` atomically when the database supports transactions, or directly otherwise. */
+  transaction<T>(fn: () => Promise<T>): Promise<T>;
+  /**
+   * Whether a failed `transaction` rolls its writes back: true on the memory adapter, SQLite and PostgreSQL, and on
+   * MongoDB replica sets and sharded clusters once connected. Without it, public transactions warn once.
+   */
+  readonly supportsRollback?: boolean;
+  /** Checks the connection with the cheapest round trip (optional; health checks read one record without it). */
+  ping?(): Promise<void>;
+  /** Locks a record until the current transaction ends, for read-modify-write updates (optional). */
+  lockForUpdate?(entity: EntityModel, id: string): Promise<void>;
+}
+
+const FIND_ALL_BATCH = 1000;
+
+/** Every record matching `where`, read in pages without counting the matches first. */
+export async function findAll(adapter: DatabaseAdapter, entity: EntityModel, where: Condition[], sort: SortField[]): Promise<StoredRecord[]> {
+  // A unique last sort key keeps the pages from overlapping.
+  const order: SortField[] = sort.some((item) => item.field === "id") ? sort : [...sort, { field: "id", direction: "asc" }];
+  const found: StoredRecord[] = [];
+  for (let offset = 0; ; offset += FIND_ALL_BATCH) {
+    const { data } = await adapter.findMany(entity, { where, sort: order, limit: FIND_ALL_BATCH, offset, withTotal: false });
+    found.push(...data);
+    if (data.length < FIND_ALL_BATCH) return found;
+  }
+}
+
+export class UniqueViolationError extends Error {
+  readonly field: string;
+
+  constructor(field: string) {
+    super(`Unique constraint violated on "${field}"`);
+    this.name = "UniqueViolationError";
+    this.field = field;
+  }
+}

package/src/adapters/memory.ts

@@ -0,0 +1,245 @@
+import {
+  UniqueViolationError,
+  type Aggregate,
+  type AggregateValues,
+  type DatabaseAdapter,
+  type FindManyOptions,
+  type FindManyResult,
+  type RelatedScope,
+  type StoredRecord,
+} from "../adapter.ts";
+import type { EntityModel } from "../model.ts";
+import { TransactionScope } from "../sql/transaction-scope.ts";
+import type { Condition, SortField } from "../query.ts";
+import { compareValues, matches } from "../matching.ts";
+
+type Table = Map<string, StoredRecord>;
+
+const isNullish = (value: unknown): boolean => value === null || value === undefined;
+
+function sortRecords(records: StoredRecord[], sort: SortField[]): StoredRecord[] {
+  return records.sort((left, right) => {
+    for (const { field, direction } of sort) {
+      const a = left[field];
+      const b = right[field];
+      let result: number;
+      // Nulls sort last ascending and first descending, as in PostgreSQL.
+      if (isNullish(a) || isNullish(b)) result = isNullish(a) === isNullish(b) ? 0 : isNullish(a) ? 1 : -1;
+      else result = compareValues(a, b);
+      if (result !== 0) return direction === "asc" ? result : -result;
+    }
+    return 0;
+  });
+}
+
+/** Computes one aggregate like SQL does: null values are skipped, and only counts are 0 without values. */
+function aggregateOf(records: StoredRecord[], aggregate: Aggregate, entity: EntityModel): number | Date | null {
+  if (aggregate.fn === "count") {
+    const where = aggregate.where ?? [];
+    return records.filter((record) => where.every((condition) => matches(record, condition, entity))).length;
+  }
+  const values = records.map((record) => record[aggregate.field]).filter((value) => !isNullish(value));
+  if (values.length === 0) return null;
+  if (aggregate.fn === "sum" || aggregate.fn === "avg") {
+    const sum = (values as number[]).reduce((total, value) => total + value, 0);
+    return aggregate.fn === "sum" ? sum : sum / values.length;
+  }
+  const pick = values.reduce((best, value) => ((aggregate.fn === "min" ? compareValues(value, best) < 0 : compareValues(value, best) > 0) ? value : best));
+  return pick instanceof Date ? new Date(pick) : (pick as number);
+}
+
+/** The record without the omitted fields. */
+function without(record: StoredRecord, omit: readonly string[] | undefined): StoredRecord {
+  for (const field of omit ?? []) delete record[field];
+  return record;
+}
+
+export function memoryAdapter(): DatabaseAdapter {
+  const tables = new Map<string, Table>();
+  // Transactions run one at a time, like on SQLite; the undo log of the running one restores what it changed.
+  const scope = new TransactionScope();
+  let undo: (() => void)[] | undefined;
+  /** Records how to restore the record `id` of `table` as it is now, when a transaction runs. */
+  const remember = (table: Table, id: string) => {
+    if (!undo) return;
+    const previous = table.get(id);
+    undo.push(() => (previous === undefined ? table.delete(id) : table.set(id, previous)));
+  };
+
+  // Each schema is its own namespace, so `users` and `auth/users` never share records.
+  const tableFor = (entity: EntityModel): Table => {
+    const key = `${entity.schema ?? ""}\u0000${entity.tableName}`;
+    let table = tables.get(key);
+    if (!table) {
+      table = new Map();
+      tables.set(key, table);
+    }
+    return table;
+  };
+
+  const select = (entity: EntityModel, where: Condition[]): StoredRecord[] =>
+    [...tableFor(entity).values()].filter((record) => where.every((condition) => matches(record, condition, entity)));
+
+  /** One page of `records`, in `sort` order. */
+  const page = (records: StoredRecord[], { sort, limit, offset, withTotal = true, omit }: FindManyOptions): FindManyResult => {
+    const sorted = sortRecords(records, sort);
+    const data = sorted.slice(offset, offset + limit).map((record) => without(structuredClone(record), omit));
+    return { data, total: withTotal ? sorted.length : data.length };
+  };
+
+  const aggregateAll = (entity: EntityModel, records: StoredRecord[], aggregates: Record<string, Aggregate>): AggregateValues => {
+    const values: AggregateValues = {};
+    for (const [name, aggregate] of Object.entries(aggregates)) values[name] = aggregateOf(records, aggregate, entity);
+    return values;
+  };
+
+  /** The related records of `scope` matching `where`, or null when the owner does not exist. */
+  const selectRelated = ({ owner, id, field, target }: RelatedScope, where: Condition[]): StoredRecord[] | null => {
+    const record = tableFor(owner).get(id);
+    if (!record) return null;
+    const records = tableFor(target);
+    const ids = new Set((record[field] as string[] | null) ?? []);
+    return [...ids].flatMap((targetId) => {
+      const found = records.get(targetId);
+      return found && where.every((condition) => matches(found, condition, target)) ? [found] : [];
+    });
+  };
+
+  const assertUnique = (entity: EntityModel, record: StoredRecord): void => {
+    for (const field of entity.fields) {
+      if (!field.unique || isNullish(record[field.name])) continue;
+      for (const other of tableFor(entity).values()) {
+        if (other.id !== record.id && compareValues(other[field.name], record[field.name]) === 0) {
+          throw new UniqueViolationError(field.name);
+        }
+      }
+    }
+    for (const { fields, unique } of entity.indexes ?? []) {
+      if (!unique) continue;
+      for (const other of tableFor(entity).values()) {
+        if (other.id !== record.id && fields.every((field) => compareValues(other[field], record[field]) === 0)) {
+          throw new UniqueViolationError(fields[0]!);
+        }
+      }
+    }
+  };
+
+  const normalize = (entity: EntityModel, record: StoredRecord): StoredRecord => {
+    const normalized: StoredRecord = { ...record };
+    for (const field of entity.fields) {
+      if (normalized[field.name] === undefined || (field.type === "refArray" && normalized[field.name] === null)) {
+        normalized[field.name] = field.type === "refArray" ? [] : null;
+      }
+    }
+    return structuredClone(normalized);
+  };
+
+  return {
+    kind: "memory",
+    supportsRollback: true,
+    async connect(models) {
+      for (const model of models) tableFor(model);
+    },
+    async disconnect() {
+      tables.clear();
+    },
+    insert(entity, record) {
+      return scope.run(() => {
+        const stored = normalize(entity, record);
+        assertUnique(entity, stored);
+        remember(tableFor(entity), stored.id);
+        tableFor(entity).set(stored.id, stored);
+        return structuredClone(stored);
+      });
+    },
+    insertOrSkip(entity, record, unique) {
+      return scope.run(() => {
+        const stored = normalize(entity, record);
+        const value = stored[unique];
+        if (value !== null && value !== undefined && [...tableFor(entity).values()].some((existing) => existing[unique] === value)) return null;
+        assertUnique(entity, stored);
+        remember(tableFor(entity), stored.id);
+        tableFor(entity).set(stored.id, stored);
+        return structuredClone(stored);
+      });
+    },
+    findById(entity, id, options) {
+      return scope.run(() => {
+        const record = tableFor(entity).get(id);
+        return record ? without(structuredClone(record), options?.omit) : null;
+      });
+    },
+    findOne(entity, where) {
+      return scope.run(() => {
+        const [record] = select(entity, where);
+        return record ? structuredClone(record) : null;
+      });
+    },
+    findMany(entity, options: FindManyOptions) {
+      return scope.run(() => page(select(entity, options.where), options));
+    },
+    findRelated(related, options) {
+      return scope.run(() => page(selectRelated(related, options.where) ?? [], options));
+    },
+    countRelated(related, where) {
+      return scope.run(() => selectRelated(related, where)?.length ?? 0);
+    },
+    aggregateRelated(related, where, aggregates) {
+      return scope.run(() => {
+        const records = selectRelated(related, where);
+        return records ? aggregateAll(related.target, records, aggregates) : null;
+      });
+    },
+    updateById(entity, id, changes, where = []) {
+      return scope.run(() => {
+        const table = tableFor(entity);
+        const current = table.get(id);
+        if (!current || !where.every((condition) => matches(current, condition, entity))) return null;
+        const updated = normalize(entity, { ...current, ...changes, id });
+        assertUnique(entity, updated);
+        remember(table, id);
+        table.set(id, updated);
+        return structuredClone(updated);
+      });
+    },
+    increment(entity, id, amounts, insert) {
+      return scope.run(() => {
+        const table = tableFor(entity);
+        const current = table.get(id);
+        const added = current ? Object.fromEntries(Object.entries(amounts).map(([field, amount]) => [field, Number(current[field] ?? 0) + amount])) : amounts;
+        const next = normalize(entity, { ...(current ?? insert), ...added, id });
+        if (!current) assertUnique(entity, next);
+        remember(table, id);
+        table.set(id, next);
+        return structuredClone(next);
+      });
+    },
+    deleteById(entity, id) {
+      return scope.run(() => {
+        remember(tableFor(entity), id);
+        return tableFor(entity).delete(id);
+      });
+    },
+    count(entity, where) {
+      return scope.run(() => select(entity, where).length);
+    },
+    aggregate(entity, where, aggregates) {
+      return scope.run(() => aggregateAll(entity, select(entity, where), aggregates));
+    },
+    async ping() {},
+    transaction(fn) {
+      return scope.transaction(fn, {
+        begin: () => {
+          undo = [];
+        },
+        commit: () => {
+          undo = undefined;
+        },
+        rollback: () => {
+          for (const restore of (undo ?? []).reverse()) restore();
+          undo = undefined;
+        },
+      });
+    },
+  };
+}