@classytic/repo-core 0.1.0

package/dist/testing/types.d.mts

@@ -0,0 +1,113 @@
+import { MinimalRepo, StandardRepo } from "../repository/types.mjs";
+
+//#region src/testing/types.d.ts
+/**
+ * The conformance scenarios operate on a minimal doc shape common to
+ * every backend:
+ *
+ *   - `name`, `email`, `category`, `active`, `count`, `notes` — plain
+ *     scalar fields every driver supports.
+ *   - `createdAt` — ISO string. Avoids Date/epoch coercion divergence.
+ *   - `_id` / `id` — the harness decides which one its backend uses;
+ *     scenarios read it via `harness.idField`.
+ *
+ * The intent is to keep the schema lowest-common-denominator, not to
+ * exercise backend-specific features (JSON mode, BSON subdocs, vector
+ * fields). Those stay per-kit.
+ */
+interface ConformanceDoc {
+  id?: string;
+  _id?: string;
+  name: string;
+  email: string;
+  category: string | null;
+  count: number;
+  active: boolean;
+  notes: string | null;
+  createdAt: string;
+}
+/**
+ * Per-backend feature flags. Scenarios that exercise a non-universal
+ * capability (transactions in D1, upsert in narrow stores) check the
+ * flag and `it.skip` on the off branch — so the suite runs on every
+ * environment without "optional test failed" noise.
+ */
+interface ConformanceFeatures {
+  /** `withTransaction(fn)` — D1 throws, standalone Mongo throws 263. */
+  transactions: boolean;
+  /**
+   * True if calling `withTransaction` inside another `withTransaction`
+   * callback is expected to work. Mongo's driver supports it via the
+   * same session; SQL drivers typically reject it. Either behavior is
+   * valid — the scenario asserts whichever the harness declares.
+   */
+  nestedTransactions: boolean;
+  /** `findOneAndUpdate` with upsert: true. */
+  upsert: boolean;
+  /** `isDuplicateKeyError(err)` classifier. */
+  duplicateKeyError: boolean;
+  /** `distinct(field)`. */
+  distinct: boolean;
+  /** Portable `aggregate({ measures, groupBy, having })`. */
+  aggregate: boolean;
+  /** `getOrCreate(filter, data)`. */
+  getOrCreate: boolean;
+  /** `count(filter)` and `exists(filter)`. */
+  countAndExists: boolean;
+}
+/**
+ * One-shot context produced by `harness.setup()`. Scenarios receive a
+ * fresh context per test — the harness is responsible for isolation
+ * (new collection name on mongo, fresh `:memory:` db on sqlite).
+ */
+interface ConformanceContext<TDoc extends ConformanceDoc = ConformanceDoc> {
+  /** Repository under test. */
+  repo: StandardRepo<TDoc> & MinimalRepo<TDoc>;
+  /**
+   * Optional secondary repository pointing at a DIFFERENT collection /
+   * table — scenarios that exercise cross-repo atomicity use it. May
+   * be omitted; scenarios that need it will skip if missing.
+   */
+  secondaryRepo?: StandardRepo<TDoc> & MinimalRepo<TDoc>;
+  /** Release resources (close db, drop collection). Must be idempotent. */
+  cleanup(): Promise<void>;
+}
+/**
+ * Harness plugged into `runStandardRepoConformance`.
+ *
+ * The harness owns:
+ *   - Backend bootstrap (mongo connection, sqlite db + migrations).
+ *   - Doc factory — returns a partial doc with default values filled in.
+ *     Scenarios call `makeDoc({ name: 'override' })` to produce inserts.
+ *   - Feature flags — declares what the backend supports.
+ *   - idField — `'id'` for sqlitekit, `'_id'` for mongokit. Scenarios
+ *     read this to project the primary key off returned docs.
+ */
+interface ConformanceHarness<TDoc extends ConformanceDoc = ConformanceDoc> {
+  /** Human-readable kit name, used as the top-level describe() label. */
+  name: string;
+  /**
+   * Name of the primary-key field on docs the repo returns. `'id'` for
+   * sqlitekit, `'_id'` for mongokit, could be `'uuid'` or anything else
+   * for future kits. Scenarios read ids via `doc[idField]`.
+   */
+  idField: string;
+  /** Feature support flags — skipped scenarios show as `skipped` in vitest output. */
+  features: ConformanceFeatures;
+  /** Create a fresh, isolated repo + cleanup closure. Called per test. */
+  setup(): Promise<ConformanceContext<TDoc>>;
+  /**
+   * Build a partial doc with fixture-safe defaults. Passed-in overrides
+   * merge on top. Do NOT include `id`/`_id` unless the caller overrides
+   * (scenarios usually let the backend assign or set one explicitly).
+   *
+   * Overrides are typed against `ConformanceDoc` (not `TDoc`) because
+   * the shared scenarios only know the common doc shape. Kits that use
+   * a wider `TDoc` with extra required fields fill those in inside
+   * their harness's `makeDoc` implementation — the scenarios never
+   * reference them.
+   */
+  makeDoc(overrides?: Partial<ConformanceDoc>): Partial<TDoc>;
+}
+//#endregion
+export { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness };

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@classytic/repo-core",
+  "version": "0.1.0",
+  "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./hooks": {
+      "types": "./dist/hooks/index.d.mts",
+      "default": "./dist/hooks/index.mjs"
+    },
+    "./operations": {
+      "types": "./dist/operations/index.d.mts",
+      "default": "./dist/operations/index.mjs"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.mts",
+      "default": "./dist/errors/index.mjs"
+    },
+    "./pagination": {
+      "types": "./dist/pagination/index.d.mts",
+      "default": "./dist/pagination/index.mjs"
+    },
+    "./repository": {
+      "types": "./dist/repository/index.d.mts",
+      "default": "./dist/repository/index.mjs"
+    },
+    "./filter": {
+      "types": "./dist/filter/index.d.mts",
+      "default": "./dist/filter/index.mjs"
+    },
+    "./query-parser": {
+      "types": "./dist/query-parser/index.d.mts",
+      "default": "./dist/query-parser/index.mjs"
+    },
+    "./context": {
+      "types": "./dist/context/index.d.mts",
+      "default": "./dist/context/index.mjs"
+    },
+    "./cache": {
+      "types": "./dist/cache/index.d.mts",
+      "default": "./dist/cache/index.mjs"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.mts",
+      "default": "./dist/schema/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.mts",
+      "default": "./dist/testing/index.mjs"
+    },
+    "./lookup": {
+      "types": "./dist/lookup/index.d.mts",
+      "default": "./dist/lookup/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "repository",
+    "repository-pattern",
+    "data-access",
+    "hooks",
+    "filter-ir",
+    "pagination",
+    "cursor-pagination",
+    "keyset-pagination",
+    "plugin-based",
+    "driver-agnostic",
+    "typescript",
+    "esm"
+  ],
+  "author": "Classytic <classytic.dev@gmail.com> (https://github.com/classytic)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/repo-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/classytic/repo-core/issues"
+  },
+  "homepage": "https://github.com/classytic/repo-core#readme",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --project unit --project integration",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:e2e": "vitest run --project e2e",
+    "test:all": "vitest run",
+    "test:watch": "vitest --project unit --project integration",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "lint": "biome check src tests",
+    "lint:fix": "biome check src tests --write",
+    "format": "biome format src tests --write",
+    "check": "biome ci src tests --diagnostic-level=error",
+    "knip": "knip",
+    "prepublishOnly": "npm run check && npm run build && npm run typecheck && npm test",
+    "publish:dry": "npm publish --dry-run --access public",
+    "publish:npm": "npm publish --access public"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@biomejs/biome": "^2.4.12",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "knip": "^6.3.0",
+    "publint": "^0.3.18",
+    "tsdown": "^0.21.8",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "vitest": "^3.0.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  }
+}