peta-orm 0.4.1 → 0.5.0

package/README.md

@@ -20,24 +20,67 @@ const page = await Post.query().with("author").orderBy("id", "asc").paginate(1,
 bun add peta-orm arktype kysely @libsql/kysely-libsql @libsql/client
 ```
 
+### Simple setup (examples, scripts)
+
 ```ts
 import { createClient } from "@libsql/client"
 import { LibsqlDialect } from "@libsql/kysely-libsql"
 import { createORM, defineModel, t } from "peta-orm"
 
-const orm = createORM({
-  dialect: new LibsqlDialect({ url: "file:my-app.db" }),
+const User = defineModel("users", {
+  columns: { id: t.integer().primaryKey(), name: t.string(255), email: t.text().unique() },
 })
 
+// Eager init — fine for scripts, one-off tasks
+const client = createClient({ url: "file::memory:?cache=shared" })
+await client.execute(
+  "CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE)",
+)
+
+const orm = createORM({ dialect: new LibsqlDialect({ client }), models: { User } })
+
+const user = await User.insert({ name: "Alice", email: "alice@test.com" })
+```
+
+### Production setup (apps, servers) — no module-level side effects
+
+Module-level side effects (database connections, schema init, ORM setup at import time) cause problems with testing, HMR, and error recovery. Use `createDb()` for lazy, safe initialization:
+
+```ts
+import { createClient } from "@libsql/client"
+import { LibsqlDialect } from "@libsql/kysely-libsql"
+import { createDb, createORM, defineModel, t } from "peta-orm"
+
 const User = defineModel("users", {
   columns: { id: t.integer().primaryKey(), name: t.string(255), email: t.text().unique() },
 })
 
-orm.registerAll(User)
+async function setup() {
+  const client = createClient({ url: "file:my-app.db" })
+  await client.execute(
+    "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE)",
+  )
+  const orm = createORM({ dialect: new LibsqlDialect({ client }) })
+  orm.registerAll(User)
+  return orm
+}
+
+/** Lazy singleton — first call creates the connection, subsequent calls reuse it. */
+export const db = createDb(setup)
 
-const user = await User.insert({ name: "Alice", email: "alice@test.com" })
+// In route handlers:
+// const orm = await db()
+// const users = await User.query().execute()
 ```
 
+The factory function runs **once** on the first `await db()` call. Importing models has zero side effects — no connection, no schema init, no unhandled promises.
+
+> [!TIP]
+> For an existing Kysely instance (e.g. from a migration runner), pass it via the `kysely` config option:
+> ```ts
+> const orm = createORM({ kysely: existingKysely })
+> ```
+
 > [!TIP]
 > See the 32 [runnable examples](./examples) for every feature. Run them with `bun run examples/XX-*.ts`.
 
@@ -70,7 +113,6 @@ const user = await User.insert({ name: "Alice", email: "alice@test.com" })
 Column definitions double as validation schemas — no separate validation step needed.
 
 ```ts
-const t = columnTypes({ schema: createArkTypeSchemaConfig() })
 
 const User = defineModel("users", {
   columns: {

package/dist/index.d.mts

@@ -1,11 +1,51 @@
 import { Dialect, Kysely } from "kysely";
 
+//#region src/columns/schema.d.ts
+interface Constraint {
+  type: string;
+  args: unknown[];
+}
+interface SchemaConfig {
+  compile(dataType: string, args: unknown[], constraints: Constraint[]): unknown;
+  parse<T>(schema: unknown, value: unknown): T;
+  assert<T>(schema: unknown, value: unknown): T;
+}
+//#endregion
+//#region src/columns/column.d.ts
+interface Column<out T = unknown> {
+  readonly arkType: unknown;
+  readonly dataType: string;
+  readonly args: readonly unknown[];
+  readonly constraints: readonly Constraint[];
+  readonly isNullable: boolean;
+  readonly isPrimaryKey: boolean;
+  readonly isUnique: boolean;
+  readonly defaultValue: unknown;
+  hasConstraint(type: string): boolean;
+  parse(value: unknown): T;
+  assert(value: unknown): T;
+  primaryKey(): Column<T>;
+  nullable(): Column<T | null>;
+  default<V>(value: V): Column<T>;
+  unique(): Column<T>;
+  index(): Column<T>;
+  min(n: number): Column<T>;
+  max(n: number): Column<T>;
+  email(): Column<T>;
+  url(): Column<T>;
+  pattern(regex: RegExp | string): Column<T>;
+  references(table: () => unknown, columns: string[]): Column<T>;
+}
+declare function createColumn<T>(schema: SchemaConfig, dataType: string, args?: unknown[], constraints?: Constraint[]): Column<T>;
+type ColumnShape = Record<string, Column>;
+type ColumnValue<C> = C extends Column<infer T> ? T : never;
+//#endregion
 //#region src/lib/kysely.d.ts
 type Database = Kysely<Record<string, never>>;
 //#endregion
 //#region src/pagination/index.d.ts
-interface Paginator {
-  readonly data: Collection;
+interface Paginator<TColumns extends ColumnShape = ColumnShape> {
+  readonly data: Collection<TColumns>;
   readonly total: number;
   readonly perPage: number;
   readonly currentPage: number;
@@ -17,11 +57,11 @@ interface Paginator {
   readonly onFirstPage: boolean;
   readonly onLastPage: boolean;
   readonly count: number;
-  map<T>(fn: (item: ModelInstance) => T): T[];
-  toJSON(): PaginatorJson;
+  map<T>(fn: (item: ModelInstance<TColumns>) => T): T[];
+  toJSON(): PaginatorJson<TColumns>;
 }
-interface PaginatorJson {
-  data: Record<string, unknown>[];
+interface PaginatorJson<TColumns extends ColumnShape = ColumnShape> {
+  data: SerializedShape<TColumns>[];
   total: number;
   perPage: number;
   currentPage: number;
@@ -34,7 +74,7 @@ interface PaginatorJson {
   onLastPage: boolean;
 }
 type PaginatedResult = PaginatorJson;
-declare function createPaginator(items: ModelInstance[], total: number, perPage: number, currentPage: number): Paginator;
+declare function createPaginator<TColumns extends ColumnShape = ColumnShape>(items: ModelInstance<TColumns>[], total: number, perPage: number, currentPage: number): Paginator<TColumns>;
 //#endregion
 //#region src/relations/base.d.ts
 type RelationType = "hasMany" | "belongsTo" | "hasOne" | "manyToMany" | "hasManyThrough";
@@ -97,14 +137,14 @@ interface UpsertGraphOptions extends InsertGraphOptions {
 }
 //#endregion
 //#region src/query/types.d.ts
-interface QueryBuilder extends PromiseLike<ModelInstance[]> {
-  execute(): Promise<ModelInstance[]>;
-  collect(): Promise<Collection>;
-  executeTakeFirst(): Promise<ModelInstance | undefined>;
-  executeTakeFirstOrThrow(): Promise<ModelInstance>;
-  find(id: number | string): Promise<ModelInstance | undefined>;
-  findOrFail(id: number | string): Promise<ModelInstance>;
-  first(): Promise<ModelInstance | undefined>;
+interface QueryBuilder<TColumns extends ColumnShape = ColumnShape> extends PromiseLike<ModelInstance<TColumns>[]> {
+  execute(): Promise<ModelInstance<TColumns>[]>;
+  collect(): Promise<Collection<TColumns>>;
+  executeTakeFirst(): Promise<ModelInstance<TColumns> | undefined>;
+  executeTakeFirstOrThrow(): Promise<ModelInstance<TColumns>>;
+  find(id: number | string): Promise<ModelInstance<TColumns> | undefined>;
+  findOrFail(id: number | string): Promise<ModelInstance<TColumns>>;
+  first(): Promise<ModelInstance<TColumns> | undefined>;
   toSQL(): {
     sql: string;
     parameters: readonly unknown[];
@@ -114,17 +154,17 @@ interface QueryBuilder extends PromiseLike<ModelInstance[]> {
   avg(column: string): Promise<number>;
   min(column: string): Promise<number>;
   max(column: string): Promise<number>;
-  withCount(relation: string): QueryBuilder;
-  withSum(relation: string, column: string): QueryBuilder;
-  withAvg(relation: string, column: string): QueryBuilder;
-  withMin(relation: string, column: string): QueryBuilder;
-  withMax(relation: string, column: string): QueryBuilder;
-  withExists(relation: string): QueryBuilder;
-  chunk(size: number, callback: (chunk: ModelInstance[]) => Promise<void>): Promise<void>;
-  paginate(page: number, perPage?: number): Promise<Paginator>;
+  withCount(relation: string): QueryBuilder<TColumns>;
+  withSum(relation: string, column: string): QueryBuilder<TColumns>;
+  withAvg(relation: string, column: string): QueryBuilder<TColumns>;
+  withMin(relation: string, column: string): QueryBuilder<TColumns>;
+  withMax(relation: string, column: string): QueryBuilder<TColumns>;
+  withExists(relation: string): QueryBuilder<TColumns>;
+  chunk(size: number, callback: (chunk: ModelInstance<TColumns>[]) => Promise<void>): Promise<void>;
+  paginate(page: number, perPage?: number): Promise<Paginator<TColumns>>;
   insertGraph(data: Record<string, unknown> | Record<string, unknown>[], options?: InsertGraphOptions): Promise<any>;
   upsertGraph(data: Record<string, unknown> | Record<string, unknown>[], options?: UpsertGraphOptions): Promise<any>;
-  with(...relations: (string | Record<string, (qb: QueryBuilder) => void>)[]): QueryBuilder;
+  with(...relations: (string | Record<string, (qb: QueryBuilder<TColumns>) => void>)[]): QueryBuilder<TColumns>;
   /**
    * Whitelist allowed relations (and nested paths) for eager loading.
    * Throws if a relation path is not in the allow list.
@@ -136,42 +176,42 @@ interface QueryBuilder extends PromiseLike<ModelInstance[]> {
    *
    * Multiple arguments are merged: `allowGraph("posts", "profile")`
    */
-  allowGraph(...expressions: string[]): QueryBuilder;
+  allowGraph(...expressions: string[]): QueryBuilder<TColumns>;
   updateMany(data: Record<string, unknown>): Promise<number>;
   deleteMany(): Promise<number>;
-  withTrashed(): QueryBuilder;
-  onlyTrashed(): QueryBuilder;
-  whereIn(column: string, values: unknown[]): QueryBuilder;
-  whereInPivot(column: string, values: unknown[]): QueryBuilder;
-  has(relationName: string): QueryBuilder;
-  whereHas(relationName: string, callback?: (qb: QueryBuilder) => void): QueryBuilder;
-  whereDoesntHave(relationName: string, callback?: (qb: QueryBuilder) => void): QueryBuilder;
-  where(column: string, operator: unknown, value?: unknown): QueryBuilder;
-  whereRef(col1: string, operator: string, col2: string): QueryBuilder;
-  orWhere(column: string, operator: unknown, value?: unknown): QueryBuilder;
-  orderBy(column: string, direction?: "asc" | "desc"): QueryBuilder;
-  limit(n: number): QueryBuilder;
-  offset(n: number): QueryBuilder;
-  select(...columns: string[]): QueryBuilder;
-  selectAll(table?: string): QueryBuilder;
-  innerJoin(table: string, lhs: string, rhs: string): QueryBuilder;
-  leftJoin(table: string, lhs: string, rhs: string): QueryBuilder;
-  groupBy(...columns: string[]): QueryBuilder;
-  having(column: string, operator: string, value: unknown): QueryBuilder;
-  withoutGlobalScope(name: string): QueryBuilder;
-  all(): QueryBuilder;
+  withTrashed(): QueryBuilder<TColumns>;
+  onlyTrashed(): QueryBuilder<TColumns>;
+  whereIn(column: string, values: unknown[]): QueryBuilder<TColumns>;
+  whereInPivot(column: string, values: unknown[]): QueryBuilder<TColumns>;
+  has(relationName: string): QueryBuilder<TColumns>;
+  whereHas(relationName: string, callback?: (qb: QueryBuilder<TColumns>) => void): QueryBuilder<TColumns>;
+  whereDoesntHave(relationName: string, callback?: (qb: QueryBuilder<TColumns>) => void): QueryBuilder<TColumns>;
+  where(column: string, operator: unknown, value?: unknown): QueryBuilder<TColumns>;
+  whereRef(col1: string, operator: string, col2: string): QueryBuilder<TColumns>;
+  orWhere(column: string, operator: unknown, value?: unknown): QueryBuilder<TColumns>;
+  orderBy(column: string, direction?: "asc" | "desc"): QueryBuilder<TColumns>;
+  limit(n: number): QueryBuilder<TColumns>;
+  offset(n: number): QueryBuilder<TColumns>;
+  select(...columns: string[]): QueryBuilder<TColumns>;
+  selectAll(table?: string): QueryBuilder<TColumns>;
+  innerJoin(table: string, lhs: string, rhs: string): QueryBuilder<TColumns>;
+  leftJoin(table: string, lhs: string, rhs: string): QueryBuilder<TColumns>;
+  groupBy(...columns: string[]): QueryBuilder<TColumns>;
+  having(column: string, operator: string, value: unknown): QueryBuilder<TColumns>;
+  withoutGlobalScope(name: string): QueryBuilder<TColumns>;
+  all(): QueryBuilder<TColumns>;
   /** @internal Access underlying Kysely builder for raw SQL operations */
   _getKyselyQb(): any;
   /** @internal Replace the underlying Kysely builder */
   _replaceKyselyQb(newQb: any): void;
-  when(condition: unknown, callback: (q: QueryBuilder) => QueryBuilder): QueryBuilder;
-  unless(condition: unknown, callback: (q: QueryBuilder) => QueryBuilder): QueryBuilder;
+  when(condition: unknown, callback: (q: QueryBuilder<TColumns>) => QueryBuilder<TColumns>): QueryBuilder<TColumns>;
+  unless(condition: unknown, callback: (q: QueryBuilder<TColumns>) => QueryBuilder<TColumns>): QueryBuilder<TColumns>;
 }
 //#endregion
 //#region src/query/builder.d.ts
-declare function createQueryBuilder(def: ModelDefinition, peta?: {
+declare function createQueryBuilder<TColumns extends ColumnShape = ColumnShape>(def: ModelDefinition<TColumns>, peta?: {
   kysely: Database;
-}): QueryBuilder;
+}): QueryBuilder<TColumns>;
 //#endregion
 //#region src/relations/related-query.d.ts
 interface RelationQuery extends QueryBuilder {
@@ -202,52 +242,13 @@ interface RelationQuery extends QueryBuilder {
  */
 type Plugin = (def: ModelDefinition) => undefined | ModelDefinition;
 //#endregion
-//#region src/columns/schema.d.ts
-interface Constraint {
-  type: string;
-  args: unknown[];
-}
-interface SchemaConfig {
-  compile(dataType: string, args: unknown[], constraints: Constraint[]): unknown;
-  parse<T>(schema: unknown, value: unknown): T;
-  assert<T>(schema: unknown, value: unknown): T;
-}
-//#endregion
-//#region src/columns/column.d.ts
-interface Column<out T = unknown> {
-  readonly arkType: unknown;
-  readonly dataType: string;
-  readonly args: readonly unknown[];
-  readonly constraints: readonly Constraint[];
-  readonly isNullable: boolean;
-  readonly isPrimaryKey: boolean;
-  readonly isUnique: boolean;
-  readonly defaultValue: unknown;
-  hasConstraint(type: string): boolean;
-  parse(value: unknown): T;
-  assert(value: unknown): T;
-  primaryKey(): Column<T>;
-  nullable(): Column<T | null>;
-  default<V>(value: V): Column<T>;
-  unique(): Column<T>;
-  index(): Column<T>;
-  min(n: number): Column<T>;
-  max(n: number): Column<T>;
-  email(): Column<T>;
-  url(): Column<T>;
-  pattern(regex: RegExp | string): Column<T>;
-  references(table: () => unknown, columns: string[]): Column<T>;
-}
-declare function createColumn<T>(schema: SchemaConfig, dataType: string, args?: unknown[], constraints?: Constraint[]): Column<T>;
-type ColumnShape = Record<string, Column>;
-type ColumnValue<C> = C extends Column<infer T> ? T : never;
-//#endregion
 //#region src/types.d.ts
 type ModelId = number & {
   readonly __brand: "ModelId";
 };
-interface ModelLike {
-  get<T = unknown>(key: string): T;
+interface ModelLike<TColumns extends ColumnShape = ColumnShape> {
+  get<K extends keyof TColumns>(key: K): ColumnValue<TColumns[K]>;
+  get(key: string): unknown;
   set(key: string, value: unknown): void;
 }
 interface ORMLike {
@@ -258,6 +259,17 @@ interface ORMLike {
   transaction<T>(fn: (trx: import("kysely").Kysely<Record<string, never>>) => Promise<T>): Promise<T>;
   readonly models: ReadonlyMap<string, ModelDefinition$1<any>>;
   getModel<T extends ColumnShape = ColumnShape>(name: string): ModelDefinition$1<T> | undefined;
+  /**
+   * Discover model definitions by scanning files matching a glob pattern.
+   *
+   * Uses `fast-glob` to resolve the pattern relative to `cwd`, then dynamically
+   * imports each matching file and collects exported `ModelDefinition` values.
+   * Does **not** auto-register — use `registerAll(...result)` to register them.
+   *
+   * @param pattern  Glob pattern (e.g. `"./src/models/**\/*.ts"`)
+   * @returns  Array of discovered model definitions
+   */
+  discover(pattern: string): Promise<ModelDefinition$1<any>[]>;
 }
 interface ModelDefinition$1<TColumns extends ColumnShape = ColumnShape> {
   readonly table: string;
@@ -265,17 +277,17 @@ interface ModelDefinition$1<TColumns extends ColumnShape = ColumnShape> {
   readonly relations: Record<string, Relation>;
   readonly name: string;
   _orm: ORMLike | null;
-  query(): QueryBuilder;
-  find(id: number | string): Promise<ModelInstance | undefined>;
-  findOrFail(id: number | string): Promise<ModelInstance>;
-  first(): Promise<ModelInstance | undefined>;
-  create(data: Record<string, unknown>): Promise<ModelInstance>;
-  insert(data: Record<string, unknown>): Promise<ModelInstance>;
-  insertMany(dataArray: Record<string, unknown>[]): Promise<ModelInstance[]>;
-  update(id: number | string, data: Record<string, unknown>): Promise<ModelInstance>;
+  query(): QueryBuilder<TColumns>;
+  find(id: number | string): Promise<ModelInstance<TColumns> | undefined>;
+  findOrFail(id: number | string): Promise<ModelInstance<TColumns>>;
+  first(): Promise<ModelInstance<TColumns> | undefined>;
+  create(data: Record<string, unknown>): Promise<ModelInstance<TColumns>>;
+  insert(data: Record<string, unknown>): Promise<ModelInstance<TColumns>>;
+  insertMany(dataArray: Record<string, unknown>[]): Promise<ModelInstance<TColumns>[]>;
+  update(id: number | string, data: Record<string, unknown>): Promise<ModelInstance<TColumns>>;
   delete(id: number | string): Promise<void>;
-  hydrate(row: Record<string, unknown>): ModelInstance;
-  on(event: string, callback: (model: ModelInstance) => void | Promise<void>): () => void;
+  hydrate(row: Record<string, unknown>): ModelInstance<TColumns>;
+  on(event: string, callback: (model: ModelInstance<TColumns>) => void | Promise<void>): () => void;
   getHooks(): HookManager;
   addGlobalScope(name: string, callback: (qb: QueryBuilder) => void): void;
   removeGlobalScope(name: string): void;
@@ -358,12 +370,15 @@ declare class Attribute<T = any> {
 }
 //#endregion
 //#region src/model/types.d.ts
-interface ModelInstance {
+/** Mapped column shape — resolves each column to its JS value type for $toJSON(). */
+type SerializedShape<TColumns extends ColumnShape> = { [K in keyof TColumns]: TColumns[K] extends Column<infer T> ? T : unknown } & Record<string, unknown>;
+interface ModelInstance<TColumns extends ColumnShape = ColumnShape> {
   readonly exists: boolean;
   readonly attributes: Record<string, unknown>;
   readonly dirtyAttributes: Record<string, unknown>;
   isDirty(key?: string): boolean;
-  get<T = unknown>(key: string): T;
+  get<K extends keyof TColumns>(key: K): ColumnValue<TColumns[K]>;
+  get(key: string): unknown;
   set(key: string, value: unknown): void;
   fill(data: Record<string, unknown>): void;
   reset(): void;
@@ -379,8 +394,8 @@ interface ModelInstance {
   $restore(): Promise<void>;
   $trashed(): boolean;
   $reload(): Promise<void>;
-  $toJSON(): Record<string, unknown>;
-  toJSON(): Record<string, unknown>;
+  $toJSON(): SerializedShape<TColumns>;
+  toJSON(): SerializedShape<TColumns>;
 }
 interface ModelDefinition<TColumns extends ColumnShape = ColumnShape> {
   readonly table: string;
@@ -388,21 +403,21 @@ interface ModelDefinition<TColumns extends ColumnShape = ColumnShape> {
   readonly relations: Record<string, Relation>;
   readonly name: string;
   _orm: ORMLike | null;
-  query(): QueryBuilder;
-  find(id: number | string): Promise<ModelInstance | undefined>;
-  findOrFail(id: number | string): Promise<ModelInstance>;
-  first(): Promise<ModelInstance | undefined>;
-  create(data: Record<string, unknown>): Promise<ModelInstance>;
-  insert(data: Record<string, unknown>): Promise<ModelInstance>;
-  insertMany(dataArray: Record<string, unknown>[]): Promise<ModelInstance[]>;
-  update(id: number | string, data: Record<string, unknown>): Promise<ModelInstance>;
+  query(): QueryBuilder<TColumns>;
+  find(id: number | string): Promise<ModelInstance<TColumns> | undefined>;
+  findOrFail(id: number | string): Promise<ModelInstance<TColumns>>;
+  first(): Promise<ModelInstance<TColumns> | undefined>;
+  create(data: Record<string, unknown>): Promise<ModelInstance<TColumns>>;
+  insert(data: Record<string, unknown>): Promise<ModelInstance<TColumns>>;
+  insertMany(dataArray: Record<string, unknown>[]): Promise<ModelInstance<TColumns>[]>;
+  update(id: number | string, data: Record<string, unknown>): Promise<ModelInstance<TColumns>>;
   delete(id: number | string): Promise<void>;
   insertGraph(data: Record<string, unknown> | Record<string, unknown>[], options?: InsertGraphOptions): Promise<any>;
   upsertGraph(data: Record<string, unknown> | Record<string, unknown>[], options?: UpsertGraphOptions): Promise<any>;
-  hydrate(row: Record<string, unknown>): ModelInstance;
-  use(plugin: Plugin): ModelDefinition;
+  hydrate(row: Record<string, unknown>): ModelInstance<TColumns>;
+  use(plugin: Plugin): ModelDefinition<TColumns>;
   makeHelper<A extends any[], R>(fn: (qb: QueryBuilder, ...args: A) => R): (...args: A) => R;
-  on(event: string, callback: (model: ModelInstance) => void | Promise<void>): () => void;
+  on(event: string, callback: (model: ModelInstance<TColumns>) => void | Promise<void>): () => void;
   getHooks(): HookManager;
   beforeDelete(callback: StaticHookCallback): () => void;
   afterDelete(callback: StaticHookCallback): () => void;
@@ -417,7 +432,6 @@ interface ModelDefinition<TColumns extends ColumnShape = ColumnShape> {
   getGlobalScopes(): Map<string, (qb: QueryBuilder) => void> | undefined;
   registerTimestamps?(createdAtCol?: string, updatedAtCol?: string): void;
   registerSoftDeletes?(deletedAtCol?: string): void;
-  discover?(): Promise<never>;
   _init(orm: ORMLike): void;
 }
 interface ModelConfig<TColumns extends ColumnShape = ColumnShape> {
@@ -433,46 +447,46 @@ interface ModelConfig<TColumns extends ColumnShape = ColumnShape> {
 }
 //#endregion
 //#region src/collection/index.d.ts
-interface Collection {
+interface Collection<TColumns extends ColumnShape = ColumnShape> {
   readonly length: number;
-  [Symbol.iterator](): Iterator<ModelInstance>;
-  at(index: number): ModelInstance | undefined;
-  first(): ModelInstance | undefined;
-  last(): ModelInstance | undefined;
-  all(): ModelInstance[];
-  findBy(id: number | string): ModelInstance | undefined;
-  find(callback: (item: ModelInstance, index: number) => boolean): ModelInstance | undefined;
-  some(callback: (item: ModelInstance, index: number) => boolean): boolean;
-  includes(item: ModelInstance): boolean;
+  [Symbol.iterator](): Iterator<ModelInstance<TColumns>>;
+  at(index: number): ModelInstance<TColumns> | undefined;
+  first(): ModelInstance<TColumns> | undefined;
+  last(): ModelInstance<TColumns> | undefined;
+  all(): ModelInstance<TColumns>[];
+  findBy(id: number | string): ModelInstance<TColumns> | undefined;
+  find(callback: (item: ModelInstance<TColumns>, index: number) => boolean): ModelInstance<TColumns> | undefined;
+  some(callback: (item: ModelInstance<TColumns>, index: number) => boolean): boolean;
+  includes(item: ModelInstance<TColumns>): boolean;
   isEmpty(): boolean;
   isNotEmpty(): boolean;
   get(key: string): unknown[];
   pluck(key: string): unknown[];
-  groupBy(key: string): Record<string, ModelInstance[]>;
-  keyBy(key: string): Record<string, ModelInstance>;
-  map<T>(fn: (item: ModelInstance, index: number) => T): T[];
-  filter(fn: (item: ModelInstance, index: number) => boolean): Collection;
-  reduce<T>(fn: (acc: T, item: ModelInstance, index: number) => T, initial: T): T;
-  forEach(fn: (item: ModelInstance, index: number) => void): void;
-  each(fn: (item: ModelInstance, index: number) => void): Collection;
-  unique(key?: string): Collection;
-  sortBy(key: string, direction?: "asc" | "desc"): Collection;
-  shuffle(): Collection;
-  take(n: number): Collection;
-  skip(n: number): Collection;
-  chunk(size: number): Collection[];
+  groupBy(key: string): Record<string, ModelInstance<TColumns>[]>;
+  keyBy(key: string): Record<string, ModelInstance<TColumns>>;
+  map<T>(fn: (item: ModelInstance<TColumns>, index: number) => T): T[];
+  filter(fn: (item: ModelInstance<TColumns>, index: number) => boolean): Collection<TColumns>;
+  reduce<T>(fn: (acc: T, item: ModelInstance<TColumns>, index: number) => T, initial: T): T;
+  forEach(fn: (item: ModelInstance<TColumns>, index: number) => void): void;
+  each(fn: (item: ModelInstance<TColumns>, index: number) => void): Collection<TColumns>;
+  unique(key?: string): Collection<TColumns>;
+  sortBy(key: string, direction?: "asc" | "desc"): Collection<TColumns>;
+  shuffle(): Collection<TColumns>;
+  take(n: number): Collection<TColumns>;
+  skip(n: number): Collection<TColumns>;
+  chunk(size: number): Collection<TColumns>[];
   sum(key: string): number;
   avg(key: string): number;
   min(key: string): number;
   max(key: string): number;
-  diff(other: Collection): Collection;
-  intersect(other: Collection): Collection;
-  concat(other: Collection): Collection;
-  push(...items: ModelInstance[]): void;
-  load(...relations: string[]): Promise<Collection>;
-  toJSON(): Record<string, unknown>[];
-}
-declare function createCollection(items?: ModelInstance[]): Collection;
+  diff(other: Collection<TColumns>): Collection<TColumns>;
+  intersect(other: Collection<TColumns>): Collection<TColumns>;
+  concat(other: Collection<TColumns>): Collection<TColumns>;
+  push(...items: ModelInstance<TColumns>[]): void;
+  load(...relations: string[]): Promise<Collection<TColumns>>;
+  toJSON(): SerializedShape<TColumns>[];
+}
+declare function createCollection<TColumns extends ColumnShape = ColumnShape>(items?: ModelInstance<TColumns>[]): Collection<TColumns>;
 //#endregion
 //#region src/columns/arktype.d.ts
 declare function createArkTypeSchemaConfig(): SchemaConfig;
@@ -499,7 +513,27 @@ interface ColumnTypes {
     updatedAt: Column<string>;
   };
 }
-declare function t(config: {
+/**
+ * Pre-configured column type factory backed by ArkType validation.
+ *
+ * The most common usage — just import and use:
+ * ```ts
+ * import { t } from "peta-orm"
+ * const id = t.integer().primaryKey()
+ * ```
+ *
+ * For a custom validation backend, use `createColumnTypes({ schema })` instead.
+ */
+declare const t: ColumnTypes;
+/**
+ * Create a column type factory with a custom validation schema backend.
+ *
+ * @example
+ * ```ts
+ * const t = createColumnTypes({ schema: myCustomSchemaConfig })
+ * ```
+ */
+declare function createColumnTypes(config: {
   schema: SchemaConfig;
 }): ColumnTypes;
 //#endregion
@@ -536,17 +570,56 @@ declare class DatabaseError extends Error {
 //#region src/errors/normalizer.d.ts
 declare function normalizeError(e: unknown, table?: string): DatabaseError;
 //#endregion
+//#region src/init.d.ts
+/**
+ * Create a lazy-initialized singleton factory.
+ *
+ * The factory function is called only once — on the first call to the returned
+ * function. Subsequent calls return the same resolved promise. This avoids
+ * module-level side effects: importing a model file won't trigger database
+ * connection or schema initialization until the first explicit `await db()`.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@libsql/client"
+ * import { LibsqlDialect } from "@libsql/kysely-libsql"
+ * import { createDb, createORM, defineModel, t } from "peta-orm"
+ *
+ * const User = defineModel("users", { columns: { ... } })
+ *
+ * async function setup() {
+ *   const client = createClient({ url: "file:my-app.db" })
+ *   await client.execute("CREATE TABLE IF NOT EXISTS users (...)") // schema init
+ *   const orm = createORM({ dialect: new LibsqlDialect({ client }) })
+ *   orm.registerAll(User)
+ *   return orm
+ * }
+ *
+ * export const db = createDb(setup)
+ * // Usage: const orm = await db()
+ * ```
+ */
+declare function createDb<T>(factory: () => Promise<T>): () => Promise<T>;
+//#endregion
 //#region src/model/define.d.ts
 declare function defineModel<TColumns extends ColumnShape>(table: string, config: ModelConfig<TColumns>): ModelDefinition<TColumns>;
 //#endregion
 //#region src/orm/index.d.ts
 interface ORMConfig {
-  dialect: Dialect;
+  /** Kysely dialect to create an internal Kysely instance. Required unless `kysely` is provided. */
+  dialect?: Dialect;
+  /** A pre-existing Kysely instance to reuse. Required unless `dialect` is provided. */
+  kysely?: Kysely<any>;
+  /** Optional map of model definitions to register immediately. */
   models?: Record<string, ModelDefinition>;
 }
 /**
  * Create an ORM instance — the central registry that wires Kysely to model definitions.
  * Replaces createPeta() from v0.x.
+ *
+ * Pass either `dialect` (to auto-create a Kysely instance) or `kysely` (to reuse one).
+ * Passing a pre-existing Kysely instance avoids creating a second connection for
+ * migration runners or other tools that already have their own Kysely.
  */
 declare function createORM(config: ORMConfig): ORMLike & {
   kysely: Database;
@@ -688,4 +761,26 @@ declare function defineMorphMany(options: MorphManyOptions): Relation;
  */
 declare function defineMorphOne(options: MorphOneOptions): Relation;
 //#endregion
-export { Attribute, type Collection, type Column, type ColumnShape, type ColumnTypes, type ColumnValue, type Constraint, DatabaseError, type DatabaseErrorCode, type HookCallback, type HookManager, type InsertGraphOptions, type LifecycleEvent, type ModelConfig, type ModelDefinition, type ModelId, type ModelInstance, ModelNotFoundError, ModelNotRegisteredError, type MorphManyOptions, type MorphOneOptions, type MorphToOptions, type ORMConfig, type ORMLike, type PaginatedResult, type Paginator, type PaginatorJson, type Plugin, type QueryBuilder, type Relation, RelationNotAllowedError, RelationNotFoundError, type RelationOptions, type RelationType, type SchemaConfig, type UpsertGraphOptions, ValidationError, belongsTo, createArkTypeSchemaConfig, createCollection, createColumn, createHookManager, createORM, createORM as createPeta, createPaginator, createQueryBuilder, defineModel, defineMorphMany, defineMorphOne, defineMorphTo, hasMany, hasManyThrough, hasOne, manyToMany, normalizeError, resolveMorphRelation, softDeletes, t, timestamps, ulid };
+//#region src/repo/index.d.ts
+type QueryMethod = (qb: QueryBuilder, ...args: any[]) => QueryBuilder;
+interface RepoMethods {
+  queryMethods?: Record<string, QueryMethod>;
+  methods?: Record<string, (...args: any[]) => any>;
+}
+/**
+ * Create a repository — a composable set of chainable query methods.
+ *
+ * ```ts
+ * const userRepo = createRepo(User, {
+ *   queryMethods: {
+ *     search(q, query: string) {
+ *       return q.where('name', 'like', `%${query}%`)
+ *     },
+ *   },
+ * })
+ * const users = await userRepo.search('john').paginate(1, 20)
+ * ```
+ */
+declare function createRepo<TMethods extends RepoMethods>(model: ModelDefinition, methods: TMethods): Record<string, never>;
+//#endregion
+export { Attribute, type Collection, type Column, type ColumnShape, type ColumnTypes, type ColumnValue, type Constraint, DatabaseError, type DatabaseErrorCode, type HookCallback, type HookManager, type InsertGraphOptions, type LifecycleEvent, type ModelConfig, type ModelDefinition, type ModelId, type ModelInstance, ModelNotFoundError, ModelNotRegisteredError, type MorphManyOptions, type MorphOneOptions, type MorphToOptions, type ORMConfig, type ORMLike, type PaginatedResult, type Paginator, type PaginatorJson, type Plugin, type QueryBuilder, type QueryMethod, type Relation, RelationNotAllowedError, RelationNotFoundError, type RelationOptions, type RelationType, type RepoMethods, type SchemaConfig, type SerializedShape, type UpsertGraphOptions, ValidationError, belongsTo, createArkTypeSchemaConfig, createCollection, createColumn, createColumnTypes, createDb, createHookManager, createORM, createORM as createPeta, createPaginator, createQueryBuilder, createRepo, defineModel, defineMorphMany, defineMorphOne, defineMorphTo, hasMany, hasManyThrough, hasOne, manyToMany, normalizeError, resolveMorphRelation, softDeletes, t, timestamps, ulid };

package/dist/index.mjs

@@ -7,6 +7,7 @@ import { a as getRawRelations, d as setExists, o as getState } from "./state-Ltl
 import { a as setConfig$1, n as reloadModel, r as saveModel, t as getConfig$1 } from "./save-D5UKXvqC.mjs";
 import { type } from "arktype";
 import { Kysely, sql } from "kysely";
+import { pathToFileURL } from "url";
 import { ulid as ulid$1 } from "ulid";
 //#region src/columns/arktype.ts
 function createArkTypeSchemaConfig() {
@@ -189,7 +190,27 @@ function createColumn(schema, dataType, args = [], constraints = []) {
 }
 //#endregion
 //#region src/columns/types.ts
-function t(config) {
+/**
+* Pre-configured column type factory backed by ArkType validation.
+*
+* The most common usage — just import and use:
+* ```ts
+* import { t } from "peta-orm"
+* const id = t.integer().primaryKey()
+* ```
+*
+* For a custom validation backend, use `createColumnTypes({ schema })` instead.
+*/
+const t = createColumnTypes({ schema: createArkTypeSchemaConfig() });
+/**
+* Create a column type factory with a custom validation schema backend.
+*
+* @example
+* ```ts
+* const t = createColumnTypes({ schema: myCustomSchemaConfig })
+* ```
+*/
+function createColumnTypes(config) {
 	const schema = config.schema;
 	function col(dataType, args) {
 		return createColumn(schema, dataType, args);
@@ -217,6 +238,43 @@ function t(config) {
 	};
 }
 //#endregion
+//#region src/init.ts
+/**
+* Create a lazy-initialized singleton factory.
+*
+* The factory function is called only once — on the first call to the returned
+* function. Subsequent calls return the same resolved promise. This avoids
+* module-level side effects: importing a model file won't trigger database
+* connection or schema initialization until the first explicit `await db()`.
+*
+* @example
+* ```ts
+* import { createClient } from "@libsql/client"
+* import { LibsqlDialect } from "@libsql/kysely-libsql"
+* import { createDb, createORM, defineModel, t } from "peta-orm"
+*
+* const User = defineModel("users", { columns: { ... } })
+*
+* async function setup() {
+*   const client = createClient({ url: "file:my-app.db" })
+*   await client.execute("CREATE TABLE IF NOT EXISTS users (...)") // schema init
+*   const orm = createORM({ dialect: new LibsqlDialect({ client }) })
+*   orm.registerAll(User)
+*   return orm
+* }
+*
+* export const db = createDb(setup)
+* // Usage: const orm = await db()
+* ```
+*/
+function createDb(factory) {
+	let promise = null;
+	return () => {
+		if (!promise) promise = factory();
+		return promise;
+	};
+}
+//#endregion
 //#region src/hooks/static.ts
 var static_exports = /* @__PURE__ */ __exportAll({
 	addStaticHook: () => addStaticHook,
@@ -1483,9 +1541,6 @@ function defineModel(table, config) {
 	def.registerSoftDeletes = (deletedAtCol) => {
 		registerSoftDeletesFor(def, deletedAtCol);
 	};
-	def.discover = async () => {
-		throw new Error("discover() not yet implemented in v2");
-	};
 	return def;
 }
 //#endregion
@@ -1895,9 +1950,14 @@ initRuntime({
 /**
 * Create an ORM instance — the central registry that wires Kysely to model definitions.
 * Replaces createPeta() from v0.x.
+*
+* Pass either `dialect` (to auto-create a Kysely instance) or `kysely` (to reuse one).
+* Passing a pre-existing Kysely instance avoids creating a second connection for
+* migration runners or other tools that already have their own Kysely.
 */
 function createORM(config) {
-	const kysely = new Kysely({ dialect: config.dialect });
+	if (!config.dialect && !config.kysely) throw new Error("createORM: provide either `dialect` (to create a Kysely instance) or `kysely` (to reuse one)");
+	const kysely = config.kysely ?? new Kysely({ dialect: config.dialect });
 	const modelMap = /* @__PURE__ */ new Map();
 	const orm = {
 		kysely,
@@ -1923,6 +1983,26 @@ function createORM(config) {
 		},
 		getModel(name) {
 			return modelMap.get(name);
+		},
+		async discover(pattern) {
+			const entries = await (await import("fast-glob")).glob(pattern, {
+				absolute: true,
+				onlyFiles: true
+			});
+			if (entries.length === 0) throw new Error(`discover: no files matched pattern "${pattern}"`);
+			const models = [];
+			const seen = /* @__PURE__ */ new Set();
+			for (const fp of entries) {
+				const mod = await import(pathToFileURL(fp).href);
+				for (const val of Object.values(mod)) if (val && typeof val === "object" && "columns" in val && "table" in val && typeof val.table === "string" && val.table.length > 0) {
+					const def = val;
+					if (!seen.has(def.table)) {
+						seen.add(def.table);
+						models.push(def);
+					}
+				}
+			}
+			return models;
 		}
 	};
 	if (config.models) for (const [_name, model] of Object.entries(config.models)) orm.register(model);
@@ -2601,4 +2681,65 @@ function defName(instance) {
 	return instance.constructor?.name ?? "model";
 }
 //#endregion
-export { Attribute, DatabaseError, ModelNotFoundError, ModelNotRegisteredError, RelationNotAllowedError, RelationNotFoundError, ValidationError, belongsTo, createArkTypeSchemaConfig, createCollection, createColumn, createHookManager, createORM, createORM as createPeta, createPaginator, createQueryBuilder, defineModel, defineMorphMany, defineMorphOne, defineMorphTo, hasMany, hasManyThrough, hasOne, eager_exports as i, manyToMany, relation_exports as n, normalizeError, delete_exports as r, resolveMorphRelation, softDeletes, t, timestamps, ulid };
+//#region src/repo/index.ts
+/**
+* Create a repository — a composable set of chainable query methods.
+*
+* ```ts
+* const userRepo = createRepo(User, {
+*   queryMethods: {
+*     search(q, query: string) {
+*       return q.where('name', 'like', `%${query}%`)
+*     },
+*   },
+* })
+* const users = await userRepo.search('john').paginate(1, 20)
+* ```
+*/
+function createRepo(model, methods) {
+	const customMethods = /* @__PURE__ */ new Map();
+	if (methods.queryMethods) for (const [name, fn] of Object.entries(methods.queryMethods)) customMethods.set(name, fn);
+	/**
+	* Wrap a QueryBuilder so custom methods are available for chaining.
+	* Custom methods operate on the CURRENT QB (not a fresh one), so
+	* chaining carries forward previous conditions.
+	*/
+	function wrapQB(qb) {
+		return new Proxy(qb, { get(target, prop) {
+			if (typeof prop === "string") {
+				if (customMethods.has(prop)) {
+					const fn = customMethods.get(prop);
+					return (...args) => {
+						return wrapQB(fn(target, ...args));
+					};
+				}
+				if (methods.methods?.[prop]) return (...args) => methods.methods[prop](...args);
+			}
+			const val = target[prop];
+			if (typeof val === "function") return function(...args) {
+				const result = val.apply(target, args);
+				return result === target ? wrapQB(result) : result;
+			};
+			return val;
+		} });
+	}
+	return new Proxy({}, { get(_target, prop) {
+		if (typeof prop === "string") {
+			if (customMethods.has(prop)) {
+				const fn = customMethods.get(prop);
+				return (...args) => {
+					return wrapQB(fn(model.query(), ...args));
+				};
+			}
+			if (methods.methods?.[prop]) return (...args) => methods.methods[prop](...args);
+		}
+		const qb = model.query();
+		const val = qb[prop];
+		if (typeof val === "function") return (...args) => {
+			return wrapQB(val.apply(qb, args));
+		};
+		return val;
+	} });
+}
+//#endregion
+export { Attribute, DatabaseError, ModelNotFoundError, ModelNotRegisteredError, RelationNotAllowedError, RelationNotFoundError, ValidationError, belongsTo, createArkTypeSchemaConfig, createCollection, createColumn, createColumnTypes, createDb, createHookManager, createORM, createORM as createPeta, createPaginator, createQueryBuilder, createRepo, defineModel, defineMorphMany, defineMorphOne, defineMorphTo, hasMany, hasManyThrough, hasOne, eager_exports as i, manyToMany, relation_exports as n, normalizeError, delete_exports as r, resolveMorphRelation, softDeletes, t, timestamps, ulid };

package/package.json

@@ -2,14 +2,14 @@
   "name": "peta-orm",
   "type": "module",
   "private": false,
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "ORM for Bun, built on Kysely",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zfadhli/peta-stack.git"
   },
-  "module": "src/index.ts",
+  "module": "./dist/index.mjs",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {
@@ -26,6 +26,7 @@
   "dependencies": {
     "arktype": "^2.2.0",
     "cac": "^7.0.0",
+    "fast-glob": "^3.3.3",
     "ora": "^9.4.0",
     "ulid": "^3.0.2"
   },
@@ -55,6 +56,6 @@
     "build": "tsdown",
     "lint": "bunx biome check src test examples",
     "lint:fix": "bunx biome check --write --unsafe src test examples",
-    "prepublish": "bun run build"
+    "prepublishOnly": "bun run build"
   }
 }