@c9up/atlas 0.2.0 → 0.2.1

package/dist/testing/TestUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestUtils.d.ts","sourceRoot":"","sources":["../../src/testing/TestUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAM5E,OAAO,EACN,KAAK,eAAe,EAGpB,MAAM,sBAAsB,CAAC;AA0B9B,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC3B,mEAAmE;IACnE,OAAO,IAAI,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,yEAAyE;IACzE,QAAQ,IAAI,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,qDAAqD;IACrD,IAAI,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;OAGG;IACH,qBAAqB,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CAClD;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CACxB,IAAI,EAAE,uBAAuB,EAC7B,OAAO,GAAE,kBAAuB,GAC9B;IAAE,EAAE,IAAI,WAAW,CAAA;CAAE,CAqCvB"}

package/dist/testing/TestUtils.js

@@ -0,0 +1,79 @@
+/**
+ * `testUtils.db()` — the AdonisJS `testUtils.db()` facade for test state
+ * management, wired to atlas's migration/seed/truncate/transaction bricks:
+ *
+ *   const t = testUtils(connection, { migrationsDir, seedersDir });
+ *   test.group("users", (group) => {
+ *     group.each.setup(() => t.db().truncate());   // teardown truncates
+ *   });
+ *
+ * Each method returns the TEARDOWN function a Japa/helix hook uses (Adonis
+ * parity): `group.each.setup(() => testUtils.db().truncate())`.
+ *
+ * NOTE (named atlas deviation): Lucid's `withGlobalTransaction()` transparently
+ * routes EVERY query through a hidden connection-global transaction. atlas
+ * deliberately does NOT bind a global transaction (it caused silent pool-scatter
+ * bugs — see `useTransaction`); instead it hands back a PINNED trx the test
+ * drives explicitly. So `withGlobalTransaction()` returns `{ trx, rollback }` —
+ * run the test's queries through `trx`, not the pooled connection.
+ */
+import { MigrationRunner, } from "../schema/MigrationRunner.js";
+import { runSeederDirectory } from "../schema/Seeder.js";
+import { truncateAll, useTransaction, } from "./DatabaseCleanup.js";
+/**
+ * Adapt a real connection to the {@link DatabaseAdapter} shape MigrationRunner
+ * needs — the only mismatch is `execute` (the connection returns row counts,
+ * the adapter wants `void`). Forwards the interactive-transaction hooks so
+ * transactional migrations + FK suspension keep working.
+ */
+function connToAdapter(conn) {
+    const adapter = {
+        execute: async (sql, params) => {
+            await conn.execute(sql, params);
+        },
+        query: (sql, params) => conn.query(sql, params),
+        close: () => conn.close(),
+    };
+    if (conn.runInTransaction) {
+        adapter.runInTransaction = (batch) => conn.runInTransaction(batch);
+    }
+    // `conn.transaction()` is the MANUAL (pinned) form; DatabaseAdapter.transaction
+    // is the MANAGED (callback) form — different shapes, so it isn't forwarded.
+    // runInTransaction covers atomic migration batches; the managed hook is only
+    // needed for `defer()`/MySQL-FK migrations, which a bare test connection skips.
+    return adapter;
+}
+/** AdonisJS `testUtils` facade (db slice) bound to a connection. */
+export function testUtils(conn, options = {}) {
+    return {
+        db() {
+            return {
+                async migrate() {
+                    const runner = new MigrationRunner(connToAdapter(conn), {
+                        migrationsDir: options.migrationsDir,
+                        dialect: conn.dialect,
+                    });
+                    await runner.migrate();
+                    return async () => {
+                        await runner.rollback();
+                    };
+                },
+                truncate() {
+                    return async () => {
+                        await truncateAll(conn, options.ignoreTables);
+                    };
+                },
+                async seed(files) {
+                    if (!options.seedersDir) {
+                        throw new Error("testUtils.db().seed() needs a `seedersDir` (pass it to testUtils()).");
+                    }
+                    await runSeederDirectory(options.seedersDir, conn, files ? { files } : undefined);
+                },
+                withGlobalTransaction() {
+                    return useTransaction(conn);
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=TestUtils.js.map

package/dist/testing/TestUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestUtils.js","sourceRoot":"","sources":["../../src/testing/TestUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAEN,eAAe,GACf,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAEN,WAAW,EACX,cAAc,GACd,MAAM,sBAAsB,CAAC;AAE9B;;;;;GAKG;AACH,SAAS,aAAa,CAAC,IAA6B;IACnD,MAAM,OAAO,GAAoB;QAChC,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE;YAC9B,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC;QAC/C,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE;KACzB,CAAC;IACF,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC3B,OAAO,CAAC,gBAAgB,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACpE,CAAC;IACD,gFAAgF;IAChF,4EAA4E;IAC5E,6EAA6E;IAC7E,gFAAgF;IAChF,OAAO,OAAO,CAAC;AAChB,CAAC;AA2BD,oEAAoE;AACpE,MAAM,UAAU,SAAS,CACxB,IAA6B,EAC7B,UAA8B,EAAE;IAEhC,OAAO;QACN,EAAE;YACD,OAAO;gBACN,KAAK,CAAC,OAAO;oBACZ,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE;wBACvD,aAAa,EAAE,OAAO,CAAC,aAAa;wBACpC,OAAO,EAAE,IAAI,CAAC,OAAO;qBACrB,CAAC,CAAC;oBACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;oBACvB,OAAO,KAAK,IAAI,EAAE;wBACjB,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;oBACzB,CAAC,CAAC;gBACH,CAAC;gBACD,QAAQ;oBACP,OAAO,KAAK,IAAI,EAAE;wBACjB,MAAM,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;oBAC/C,CAAC,CAAC;gBACH,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,KAAK;oBACf,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;wBACzB,MAAM,IAAI,KAAK,CACd,sEAAsE,CACtE,CAAC;oBACH,CAAC;oBACD,MAAM,kBAAkB,CACvB,OAAO,CAAC,UAAU,EAClB,IAAI,EACJ,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAC7B,CAAC;gBACH,CAAC;gBACD,qBAAqB;oBACpB,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;gBAC7B,CAAC;aACD,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/testing/index.d.ts

@@ -1,4 +1,6 @@
 export { truncateAll, useTransaction } from "./DatabaseCleanup.js";
-export { type FactoryBuilder, factory } from "./Factory.js";
+export { createDbAssertions, type DbAssertions, type DbConnectionLike, db, } from "./DbAssertions.js";
+export { Factory, type FactoryBuilder, factory } from "./Factory.js";
 export { Database } from "./TestDatabase.js";
+export { type DbTestUtils, type DbTestUtilsOptions, testUtils, } from "./TestUtils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EACN,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,EAAE,GACF,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,SAAS,GACT,MAAM,gBAAgB,CAAC"}

package/dist/testing/index.js

@@ -1,4 +1,6 @@
 export { truncateAll, useTransaction } from "./DatabaseCleanup.js";
-export { factory } from "./Factory.js";
+export { createDbAssertions, db, } from "./DbAssertions.js";
+export { Factory, factory } from "./Factory.js";
 export { Database } from "./TestDatabase.js";
+export { testUtils, } from "./TestUtils.js";
 //# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAuB,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EACN,kBAAkB,EAGlB,EAAE,GACF,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAuB,OAAO,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAGN,SAAS,GACT,MAAM,gBAAgB,CAAC"}

package/dist/types/relations.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@c9up/atlas/types/relations` — Adonis Lucid `@adonisjs/lucid/types/relations`
+ * parity subpath.
+ *
+ * Lucid declares relation properties as `declare posts: HasMany<typeof Post>`.
+ * Atlas declares them as the plain related shape (`declare posts: Post[]`), so
+ * these helpers simply RESOLVE to that shape — a Lucid-style declaration
+ * type-checks against atlas's decorators and hydration unchanged:
+ *
+ *     import type { HasMany, BelongsTo } from '@c9up/atlas/types/relations'
+ *
+ *     class Post extends BaseModel {
+ *       @belongsTo(() => User) declare author: BelongsTo<typeof User>
+ *     }
+ *     class User extends BaseModel {
+ *       @hasMany(() => Post) declare posts: HasMany<typeof Post>
+ *     }
+ */
+/** A `hasOne` related row, or `null` when absent (resolves to `InstanceType<Related>`). */
+export type HasOne<Related extends new (...args: never[]) => unknown> = InstanceType<Related> | null;
+/** A `belongsTo` owner row, or `null` when absent. */
+export type BelongsTo<Related extends new (...args: never[]) => unknown> = InstanceType<Related> | null;
+/** A `hasMany` collection. */
+export type HasMany<Related extends new (...args: never[]) => unknown> = Array<InstanceType<Related>>;
+/** A `manyToMany` collection. */
+export type ManyToMany<Related extends new (...args: never[]) => unknown> = Array<InstanceType<Related>>;
+/** A `hasOneThrough` related row, or `null` when absent. */
+export type HasOneThrough<Related extends new (...args: never[]) => unknown> = InstanceType<Related> | null;
+/** A `hasManyThrough` collection. */
+export type HasManyThrough<Related extends new (...args: never[]) => unknown> = Array<InstanceType<Related>>;
+//# sourceMappingURL=relations.d.ts.map

package/dist/types/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../src/types/relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,2FAA2F;AAC3F,MAAM,MAAM,MAAM,CAAC,OAAO,SAAS,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,IACnE,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AAE9B,sDAAsD;AACtD,MAAM,MAAM,SAAS,CAAC,OAAO,SAAS,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,IACtE,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AAE9B,8BAA8B;AAC9B,MAAM,MAAM,OAAO,CAAC,OAAO,SAAS,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,IAAI,KAAK,CAC7E,YAAY,CAAC,OAAO,CAAC,CACrB,CAAC;AAEF,iCAAiC;AACjC,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,IACvE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;AAE9B,4DAA4D;AAC5D,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,IAC1E,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AAE9B,qCAAqC;AACrC,MAAM,MAAM,cAAc,CAAC,OAAO,SAAS,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,IAC3E,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC"}

package/dist/types/relations.js

@@ -0,0 +1,20 @@
+/**
+ * `@c9up/atlas/types/relations` — Adonis Lucid `@adonisjs/lucid/types/relations`
+ * parity subpath.
+ *
+ * Lucid declares relation properties as `declare posts: HasMany<typeof Post>`.
+ * Atlas declares them as the plain related shape (`declare posts: Post[]`), so
+ * these helpers simply RESOLVE to that shape — a Lucid-style declaration
+ * type-checks against atlas's decorators and hydration unchanged:
+ *
+ *     import type { HasMany, BelongsTo } from '@c9up/atlas/types/relations'
+ *
+ *     class Post extends BaseModel {
+ *       @belongsTo(() => User) declare author: BelongsTo<typeof User>
+ *     }
+ *     class User extends BaseModel {
+ *       @hasMany(() => Post) declare posts: HasMany<typeof Post>
+ *     }
+ */
+export {};
+//# sourceMappingURL=relations.js.map

package/dist/types/relations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.js","sourceRoot":"","sources":["../../src/types/relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@c9up/atlas",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Atlas — Data Mapper ORM for the Ream framework",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "AUDIT-migration-templates.md",
     "LICENSE",
     "README.md",
     "db.*.node",
@@ -36,6 +35,26 @@
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
+    },
+    "./orm": {
+      "types": "./dist/orm.d.ts",
+      "import": "./dist/orm.js"
+    },
+    "./schema": {
+      "types": "./dist/lucid-schema.d.ts",
+      "import": "./dist/lucid-schema.js"
+    },
+    "./factories": {
+      "types": "./dist/factories.d.ts",
+      "import": "./dist/factories.js"
+    },
+    "./seeders": {
+      "types": "./dist/seeders.d.ts",
+      "import": "./dist/seeders.js"
+    },
+    "./types/relations": {
+      "types": "./dist/types/relations.d.ts",
+      "import": "./dist/types/relations.js"
     }
   },
   "dependencies": {
@@ -43,8 +62,17 @@
     "@faker-js/faker": "^9",
     "reflect-metadata": "^0.2"
   },
+  "peerDependencies": {
+    "@c9up/helix": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@c9up/helix": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
+    "@c9up/helix": "^0.1.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2",
     "@types/node": "^22"