peta-orm 0.4.1 → 0.6.0

package/dist/index.d.mts

@@ -1,11 +1,76 @@
 import { Dialect, Kysely } from "kysely";
 
-//#region src/lib/kysely.d.ts
+//#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 Database = Kysely<Record<string, never>>;
+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 {
+  readonly kysely: Database;
+  register(model: ModelDefinition<any>): void;
+  registerAll(...models: (ModelDefinition<any> | ModelDefinition<any>[])[]): void;
+  destroy(): Promise<void>;
+  transaction<T>(fn: (orm: ORMLike) => Promise<T>): Promise<T>;
+  readonly models: ReadonlyMap<string, ModelDefinition<any>>;
+  getModel<T extends ColumnShape = ColumnShape>(name: string): ModelDefinition<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<any>[]>;
+}
 //#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;
@@ -16,12 +81,10 @@ interface Paginator {
   readonly lastItem: number;
   readonly onFirstPage: boolean;
   readonly onLastPage: boolean;
-  readonly count: number;
-  map<T>(fn: (item: ModelInstance) => T): T[];
-  toJSON(): PaginatorJson;
+  toJSON(): PaginatorJson<TColumns>;
 }
-interface PaginatorJson {
-  data: Record<string, unknown>[];
+interface PaginatorJson<TColumns extends ColumnShape = ColumnShape> {
+  data: SerializedShape<TColumns>[];
   total: number;
   perPage: number;
   currentPage: number;
@@ -33,8 +96,13 @@ interface PaginatorJson {
   onFirstPage: boolean;
   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/graph/delete.d.ts
+interface DeleteGraphOptions {
+  allowedRelations?: string[];
+}
+declare function deleteGraph(def: ModelDefinition, model: ModelInstance, options?: DeleteGraphOptions): Promise<void>;
 //#endregion
 //#region src/relations/base.d.ts
 type RelationType = "hasMany" | "belongsTo" | "hasOne" | "manyToMany" | "hasManyThrough";
@@ -97,14 +165,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 +182,14 @@ 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>;
+  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;
+  upsert(data: Record<string, unknown>): Promise<ModelInstance<TColumns>>;
+  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 +201,50 @@ 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>;
+  has(relationName: string): QueryBuilder<TColumns>;
+  /**
+   * Filter rows by related model existence with optional subquery filtering.
+   * The callback receives a raw Kysely subquery builder for the related table,
+   * not a peta-orm QueryBuilder. Chain `.where(...)` etc. directly on it.
+   */
+  whereHas(relationName: string, callback?: (subQb: any) => any): QueryBuilder<TColumns>;
+  /**
+   * Filter rows by absence of related model, with optional subquery filtering.
+   * Same callback semantics as `whereHas`.
+   */
+  whereDoesntHave(relationName: string, callback?: (subQb: any) => any): 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,87 +275,6 @@ 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;
-  set(key: string, value: unknown): void;
-}
-interface ORMLike {
-  readonly kysely: Database;
-  register(model: ModelDefinition$1<any>): void;
-  registerAll(...models: (ModelDefinition$1<any> | ModelDefinition$1<any>[])[]): void;
-  destroy(): Promise<void>;
-  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;
-}
-interface ModelDefinition$1<TColumns extends ColumnShape = ColumnShape> {
-  readonly table: string;
-  readonly columns: TColumns;
-  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>;
-  delete(id: number | string): Promise<void>;
-  hydrate(row: Record<string, unknown>): ModelInstance;
-  on(event: string, callback: (model: ModelInstance) => void | Promise<void>): () => void;
-  getHooks(): HookManager;
-  addGlobalScope(name: string, callback: (qb: QueryBuilder) => void): void;
-  removeGlobalScope(name: string): void;
-  getGlobalScopes(): Map<string, (qb: QueryBuilder) => void> | undefined;
-  _init(orm: ORMLike): void;
-}
-//#endregion
 //#region src/hooks/index.d.ts
 type LifecycleEvent = "beforeCreate" | "afterCreate" | "beforeUpdate" | "afterUpdate" | "beforeSave" | "afterSave" | "beforeDelete" | "afterDelete" | "beforeRestore" | "afterRestore" | "beforeForceDelete" | "afterForceDelete";
 type HookCallback = (model: ModelLike) => void | Promise<void>;
@@ -290,7 +282,6 @@ interface HookManager {
   on(event: LifecycleEvent, callback: HookCallback): () => void;
   off(event: LifecycleEvent, callback: HookCallback): void;
   trigger(event: LifecycleEvent, model: ModelLike): Promise<void>;
-  clone(): HookManager;
 }
 declare function createHookManager(): HookManager;
 //#endregion
@@ -307,14 +298,12 @@ type StaticHookCallback = (args: StaticHookArgs) => void | Promise<void>;
 //#endregion
 //#region src/model/computed.d.ts
 interface ComputedColumn<T = unknown> {
-  readonly type: "sql" | "runtime" | "batch";
+  readonly type: "runtime" | "batch";
   readonly dependencies: string[];
   /** Compute a value for a single record (runtime) */
   compute?: (record: ModelInstance) => T;
   /** Compute values for a batch of records (batch async) */
   batchCompute?: (records: ModelInstance[]) => Promise<T[]>;
-  /** Raw SQL expression to inline in SELECT */
-  sql?: string;
 }
 //#endregion
 //#region src/model/attribute.d.ts
@@ -358,12 +347,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 +371,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,36 +380,34 @@ 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>[]>;
+  updateMany(data: Record<string, unknown>, where: Record<string, unknown>[]): Promise<number>;
+  deleteMany(where: Record<string, unknown>[]): Promise<number>;
+  update(id: number | string, data: Record<string, unknown>): Promise<ModelInstance<TColumns>>;
   delete(id: number | string): Promise<void>;
+  deleteGraph(idOrInstance: any, options?: DeleteGraphOptions): 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;
+  upsert(data: Record<string, unknown>): Promise<ModelInstance<TColumns>>;
+  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;
   beforeUpdate(callback: StaticHookCallback): () => void;
-  afterUpdate(callback: StaticHookCallback): () => void;
-  beforeCreate(callback: StaticHookCallback): () => void;
-  afterCreate(callback: StaticHookCallback): () => void;
-  beforeFind(callback: StaticHookCallback): () => void;
-  afterFind(callback: StaticHookCallback): () => void;
   addGlobalScope(name: string, callback: (qb: QueryBuilder) => void): void;
   removeGlobalScope(name: string): void;
   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 +423,45 @@ 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;
+  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 +488,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 +545,74 @@ 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/integrations/elysia.d.ts
+interface PetaElysiaPluginOptions {
+  peta: ORMLike;
+}
+/**
+ * Elysia.js plugin that attaches the ORM instance to the app context.
+ */
+declare function petaPlugin(options: PetaElysiaPluginOptions): (app: any) => any;
+//#endregion
+//#region src/integrations/hono.d.ts
+interface PetaHonoMiddlewareOptions {
+  peta: ORMLike;
+}
+/**
+ * Hono middleware that sets the ORM instance on the context.
+ */
+declare function petaMiddleware(options: PetaHonoMiddlewareOptions): (c: any, next: any) => Promise<void>;
+//#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;
@@ -596,6 +662,42 @@ declare function timestamps(opts?: {
  */
 declare function ulid(): Plugin;
 //#endregion
+//#region src/relations/crud.d.ts
+interface BelongsToOp {
+  create?: Record<string, unknown>;
+  connect?: Record<string, unknown>;
+  connectOrCreate?: {
+    where: Record<string, unknown>;
+    create: Record<string, unknown>;
+  };
+  update?: Record<string, unknown>;
+  upsert?: {
+    update: Record<string, unknown>;
+    create: Record<string, unknown>;
+  };
+  delete?: boolean;
+  disconnect?: boolean;
+  set?: Record<string, unknown>;
+}
+interface HasManyOp {
+  create?: Record<string, unknown>[];
+  connect?: (number | string | Record<string, unknown>)[];
+  set?: (number | string | Record<string, unknown>)[];
+  delete?: Record<string, unknown> | Record<string, unknown>[];
+  update?: {
+    where: Record<string, unknown> | Record<string, unknown>[];
+    data: Record<string, unknown>;
+  };
+}
+interface ManyToManyOp {
+  create?: Record<string, unknown>[];
+  connect?: (number | string | Record<string, unknown>)[];
+  disconnect?: Record<string, unknown> | Record<string, unknown>[];
+  set?: (number | string | Record<string, unknown>)[];
+  add?: (number | string | Record<string, unknown>)[];
+}
+type RelationData = BelongsToOp | HasManyOp | ManyToManyOp;
+//#endregion
 //#region src/relations/has-many.d.ts
 declare function hasMany(relatedThunk: () => ModelDefinition, options?: RelationOptions): Relation;
 declare function hasOne(relatedThunk: () => ModelDefinition, options?: RelationOptions): Relation;
@@ -636,13 +738,6 @@ interface MorphManyOptions {
    */
   typeValue?: string;
 }
-interface MorphOneOptions {
-  name: string;
-  related: () => ModelDefinition;
-  type?: string;
-  id?: string;
-  typeValue?: string;
-}
 /**
  * Resolve the related model for a MorphTo relation given a parent instance.
  * Looks up the parent's `{name}Type` column value in the relation's morphMap
@@ -683,9 +778,27 @@ declare function defineMorphTo(options: MorphToOptions): Relation;
  * The related table stores the parent's type and id.
  */
 declare function defineMorphMany(options: MorphManyOptions): Relation;
+//#endregion
+//#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>;
+}
 /**
- * Define a polymorphic hasOne relationship.
+ * 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 defineMorphOne(options: MorphOneOptions): Relation;
+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 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 };
+export { Attribute, type BelongsToOp, type Collection, type Column, type ColumnShape, type ColumnTypes, type ColumnValue, type Constraint, DatabaseError, type DatabaseErrorCode, type DeleteGraphOptions, type HasManyOp, type HookCallback, type HookManager, type InsertGraphOptions, type LifecycleEvent, type ManyToManyOp, type ModelConfig, type ModelDefinition, type ModelInstance, ModelNotFoundError, ModelNotRegisteredError, type MorphManyOptions, type MorphToOptions, type ORMConfig, type ORMLike, type Paginator, type PaginatorJson, type Plugin, type QueryBuilder, type QueryMethod, type Relation, type RelationData, 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, defineMorphTo, deleteGraph, hasMany, hasManyThrough, hasOne, manyToMany, normalizeError, petaMiddleware, petaPlugin, resolveMorphRelation, softDeletes, t, timestamps, ulid };