peta-orm 0.4.0 → 0.5.0

package/dist/index.d.mts

@@ -1,6 +1,493 @@
-import { A as PaginatorJson, C as InsertGraphOptions, D as RelationType, E as RelationOptions, M as Database, O as PaginatedResult, S as QueryBuilder, T as Relation, _ as createColumn, a as ModelDefinition, b as Plugin, c as HookCallback, d as createHookManager, f as ModelId, g as ColumnValue, h as ColumnShape, i as ModelConfig, j as createPaginator, k as Paginator, l as HookManager, m as Column, n as Collection, o as ModelInstance, p as ORMLike, r as createCollection, s as Attribute, t as defineModel, u as LifecycleEvent, v as Constraint, w as UpsertGraphOptions, x as createQueryBuilder, y as SchemaConfig } from "./index-BdJnSMYi.mjs";
-import { Dialect } from "kysely";
+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<TColumns extends ColumnShape = ColumnShape> {
+  readonly data: Collection<TColumns>;
+  readonly total: number;
+  readonly perPage: number;
+  readonly currentPage: number;
+  readonly lastPage: number;
+  readonly hasMorePages: boolean;
+  readonly hasPages: boolean;
+  readonly firstItem: number;
+  readonly lastItem: number;
+  readonly onFirstPage: boolean;
+  readonly onLastPage: boolean;
+  readonly count: number;
+  map<T>(fn: (item: ModelInstance<TColumns>) => T): T[];
+  toJSON(): PaginatorJson<TColumns>;
+}
+interface PaginatorJson<TColumns extends ColumnShape = ColumnShape> {
+  data: SerializedShape<TColumns>[];
+  total: number;
+  perPage: number;
+  currentPage: number;
+  lastPage: number;
+  hasMorePages: boolean;
+  hasPages: boolean;
+  firstItem: number | null;
+  lastItem: number | null;
+  onFirstPage: boolean;
+  onLastPage: boolean;
+}
+type PaginatedResult = PaginatorJson;
+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";
+interface RelationOptions {
+  foreignKey?: string;
+  localKey?: string;
+  through?: string;
+  foreignPivotKey?: string;
+  relatedPivotKey?: string;
+  throughForeignKey?: string;
+  throughLocalKey?: string;
+  pivotExtras?: string[];
+}
+interface Relation {
+  readonly type: RelationType;
+  readonly relatedModelClass: ModelDefinition;
+  readonly foreignKey: string;
+  readonly localKey: string;
+  readonly throughTable?: string;
+  readonly foreignPivotKey?: string;
+  readonly relatedPivotKey?: string;
+  readonly throughForeignKey?: string;
+  readonly throughLocalKey?: string;
+  _morphMap?: Record<string, () => ModelDefinition>;
+  _morphType?: string;
+  _morphId?: string;
+  _morphTypeValue?: string;
+  query(parent: ModelInstance): QueryBuilder;
+  addEagerConstraints(query: QueryBuilder, models: ModelInstance[]): void;
+  match(models: ModelInstance[], results: ModelInstance[], relationName: string): void;
+  getResults(parent: ModelInstance): Promise<ModelInstance | ModelInstance[] | null>;
+  loadEager(models: ModelInstance[], relationName: string, constraints?: ((qb: QueryBuilder) => void) | null): Promise<void>;
+}
+//#endregion
+//#region src/relations/graph/types.d.ts
+interface InsertGraphOptions {
+  /** Allow `#id` / `#ref` special properties in the graph */
+  allowRefs?: boolean;
+  /**
+   * If `true`, objects with an `id` property get related (pivot row / FK set)
+   * instead of inserted. Can be an array of relation names to scope.
+   */
+  relate?: boolean | string[];
+  /**
+   * Whitelist of relation paths allowed for this graph operation.
+   * Accepts an array of dotted paths or a Set. If not set, all relations are allowed.
+   * When used via the query builder, the QB's `allowGraph()` set is forwarded automatically.
+   */
+  allowGraph?: string[] | Set<string>;
+}
+interface UpsertGraphOptions extends InsertGraphOptions {
+  /** Unrelate (set FK null / remove pivot) instead of deleting missing items */
+  unrelate?: boolean | string[];
+  /** Prevent deletion for all or specific relation paths */
+  noDelete?: boolean | string[];
+  /** Prevent insertion for all or specific relation paths */
+  noInsert?: boolean | string[];
+  /** Prevent update for all or specific relation paths */
+  noUpdate?: boolean | string[];
+}
+//#endregion
+//#region src/query/types.d.ts
+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[];
+  };
+  count(): Promise<number>;
+  sum(column: string): Promise<number>;
+  avg(column: string): Promise<number>;
+  min(column: string): Promise<number>;
+  max(column: string): Promise<number>;
+  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<TColumns>) => void>)[]): QueryBuilder<TColumns>;
+  /**
+   * Whitelist allowed relations (and nested paths) for eager loading.
+   * Throws if a relation path is not in the allow list.
+   *
+   * Supports dotted paths for granular control:
+   * - `allowGraph("posts")` allows `posts`, `posts.author`, `posts.author.profile`, etc.
+   * - `allowGraph("posts.author")` allows `posts.author` and `posts.author.profile`,
+   *   but NOT bare `posts` or `posts.comments`.
+   *
+   * Multiple arguments are merged: `allowGraph("posts", "profile")`
+   */
+  allowGraph(...expressions: string[]): QueryBuilder<TColumns>;
+  updateMany(data: Record<string, unknown>): Promise<number>;
+  deleteMany(): Promise<number>;
+  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<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<TColumns extends ColumnShape = ColumnShape>(def: ModelDefinition<TColumns>, peta?: {
+  kysely: Database;
+}): QueryBuilder<TColumns>;
+//#endregion
+//#region src/relations/related-query.d.ts
+interface RelationQuery extends QueryBuilder {
+  /** Attach related model(s) for many-to-many relations. */
+  attach(ids: number | number[] | string | string[], pivotData?: Record<string, unknown>): Promise<void>;
+  /** Detach related model(s) for many-to-many relations. */
+  detach(ids?: number | number[] | string | string[]): Promise<void>;
+  /** Sync related models: attaches new IDs, detaches missing ones. */
+  sync(ids: (number | string)[] | Record<number | string, Record<string, unknown>>): Promise<void>;
+  /** Sync without detaching existing IDs. */
+  syncWithoutDetaching(ids: (number | string)[]): Promise<void>;
+  /** Update pivot data for a specific related model. */
+  updateExistingPivot(id: number | string, data: Record<string, unknown>): Promise<void>;
+}
+//#endregion
+//#region src/plugins/index.d.ts
+/**
+ * A plugin is a function that receives a model definition and can
+ * modify it by adding hooks, scopes, columns, or methods.
+ *
+ * ```ts
+ * const myPlugin = (options?: MyOptions): Plugin =>
+ *   (def) => {
+ *     def.addGlobalScope?.('active', (q) => q.where('active', true))
+ *     return def
+ *   }
+ * ```
+ */
+type Plugin = (def: ModelDefinition) => undefined | ModelDefinition;
+//#endregion
+//#region src/types.d.ts
+type ModelId = number & {
+  readonly __brand: "ModelId";
+};
+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$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;
+  /**
+   * 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;
+  readonly columns: TColumns;
+  readonly relations: Record<string, Relation>;
+  readonly name: string;
+  _orm: ORMLike | null;
+  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<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;
+  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>;
+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
+//#region src/hooks/static.d.ts
+interface StaticHookArgs {
+  /** Transform the mutating query into a SELECT to preview affected rows */
+  asFindQuery(): QueryBuilder;
+  /** Cancel the mutation and return a custom result */
+  cancelQuery(result: unknown): void;
+  /** The column data being inserted/updated (for create/update hooks) */
+  inputItems?: Record<string, unknown>[];
+}
+type StaticHookCallback = (args: StaticHookArgs) => void | Promise<void>;
+//#endregion
+//#region src/model/computed.d.ts
+interface ComputedColumn<T = unknown> {
+  readonly type: "sql" | "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
+/**
+ * Defines an accessor (`get`) and/or mutator (`set`) for a model attribute.
+ *
+ * ### Accessor (get)
+ * Transforms the attribute value when read via `model.get()` or `model.$toJSON()`.
+ * Receives the casted value and the model instance.
+ *
+ * ### Mutator (set)
+ * Transforms the attribute value when written via `model.set()`, `model.fill()`,
+ * or during model creation (`Model.insert()` / `Model.create()`).
+ * Receives the raw input value and the model instance, returns the value to store.
+ * Applied **before** type casting.
+ *
+ * ### Usage
+ * ```ts
+ * defineModel('users', {
+ *   columns: { id, name, password, ... },
+ *   attributes: {
+ *     password: Attribute.make({
+ *       set: (value) => Bun.password.hashSync(value, { algorithm: 'bcrypt' }),
+ *       get: () => '***',
+ *     }),
+ *     fullName: Attribute.make({
+ *       get: (_, instance) => `${instance.get('firstName')} ${instance.get('lastName')}`,
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+declare class Attribute<T = any> {
+  readonly get?: ((value: T, instance: ModelInstance) => any) | undefined;
+  readonly set?: ((value: any, instance: ModelInstance) => T) | undefined;
+  private constructor();
+  static make<T = any>(config: {
+    /** Transform the attribute value when read. Receives (castedValue, instance). */get?: (value: T, instance: ModelInstance) => any; /** Transform the attribute value when written. Receives (rawValue, instance), returns value to store. */
+    set?: (value: any, instance: ModelInstance) => T;
+  }): Attribute<T>;
+}
+//#endregion
+//#region src/model/types.d.ts
+/** 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<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;
+  $getRelation<T = unknown>(name: string): T;
+  $setRelation(name: string, value: unknown): void;
+  $hasRelation(name: string): boolean;
+  $relationData(): Record<string, unknown>;
+  $load(...relations: string[]): Promise<void>;
+  $related(name: string): RelationQuery;
+  $save(): Promise<this>;
+  $delete(): Promise<void>;
+  $forceDelete(): Promise<void>;
+  $restore(): Promise<void>;
+  $trashed(): boolean;
+  $reload(): Promise<void>;
+  $toJSON(): SerializedShape<TColumns>;
+  toJSON(): SerializedShape<TColumns>;
+}
+interface ModelDefinition<TColumns extends ColumnShape = ColumnShape> {
+  readonly table: string;
+  readonly columns: TColumns;
+  readonly relations: Record<string, Relation>;
+  readonly name: string;
+  _orm: ORMLike | null;
+  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<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<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;
+  _init(orm: ORMLike): void;
+}
+interface ModelConfig<TColumns extends ColumnShape = ColumnShape> {
+  columns: TColumns;
+  relations?: Record<string, Relation>;
+  casts?: Record<string, string>;
+  /** Per-attribute accessors (`get`) and/or mutators (`set`). See {@link Attribute.make}. */
+  attributes?: Record<string, Attribute<any>>;
+  hidden?: string[];
+  visible?: string[];
+  appends?: string[];
+  computed?: Record<string, ComputedColumn>;
+}
+//#endregion
+//#region src/collection/index.d.ts
+interface Collection<TColumns extends ColumnShape = ColumnShape> {
+  readonly length: number;
+  [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<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<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;
 //#endregion
@@ -26,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
@@ -63,14 +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;
@@ -212,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 };