flint-orm 0.4.1 → 0.4.3

package/dist/schema/columns.d.ts

@@ -0,0 +1,146 @@
+/** Foreign key referential action. */
+export type ForeignKeyAction = 'cascade' | 'set null' | 'set default' | 'restrict' | 'no action';
+/**
+ * A column definition with chainable modifiers.
+ *
+ * @example
+ * const name = text("name").notNull().default("unnamed");
+ */
+export interface ColumnDef<T, S extends string = string> {
+    readonly name: string;
+    primaryKey(): ColumnDef<T, S>;
+    notNull(): ColumnDef<T, S>;
+    unique(): ColumnDef<T, S>;
+    /** Set a static default value used when the value is omitted during insert. */
+    default(value: T): ColumnDef<T, S>;
+    /** Set a dynamic default function called when the value is omitted during insert. */
+    defaultFn(fn: () => T): ColumnDef<T, S>;
+    /**
+     * Define a foreign key reference to another table's column.
+     *
+     * @example
+     * text("userId").references(users.id)
+     */
+    references(target: ColumnDef<any, any>): ColumnDef<T, S>;
+    /** Set ON DELETE action for the foreign key. Requires `.references()` to be called first. */
+    onDelete(action: ForeignKeyAction): ColumnDef<T, S>;
+    /** Set ON UPDATE action for the foreign key. Requires `.references()` to be called first. */
+    onUpdate(action: ForeignKeyAction): ColumnDef<T, S>;
+    readonly __internal: {
+        /** Phantom — exists only at the type level, never accessed at runtime. */
+        readonly _type: T;
+        /** SQLite storage class: "text" | "integer" | "real" | "blob". */
+        readonly sqlType: S;
+        /** Column constraint flags — set via modifiers, read by migration generator. */
+        readonly isPrimaryKey: boolean;
+        readonly isNotNull: boolean;
+        readonly isUnique: boolean;
+        readonly hasDefault: boolean;
+        readonly defaultValue: T | undefined;
+        readonly defaultFn: (() => T) | undefined;
+        readonly isAutoIncrement: boolean;
+        readonly hasDefaultNow: boolean;
+        readonly hasOnUpdate: boolean;
+        /** Foreign key reference — table and column names. */
+        readonly referencesTable: string | null;
+        readonly referencesColumn: string | null;
+        /** Foreign key referential actions. */
+        readonly onDelete: ForeignKeyAction | null;
+        readonly onUpdate: ForeignKeyAction | null;
+        /** Converts logical value → storage value. Called by the builder. */
+        readonly encode: (value: T) => unknown;
+        /** Converts storage value → logical value. Called by the builder. */
+        readonly decode: (value: unknown) => T;
+        /** Table name — set by table() when the column is attached. Used for join disambiguation. */
+        readonly tableName: string | null;
+    };
+}
+/** An integer column definition with auto-increment support. */
+export interface IntegerColumnDef<S extends string = 'integer'> extends ColumnDef<number, S> {
+    primaryKey(): IntegerColumnDef<S>;
+    notNull(): IntegerColumnDef<S>;
+    unique(): IntegerColumnDef<S>;
+    default(value: number): IntegerColumnDef<S>;
+    defaultFn(fn: () => number): IntegerColumnDef<S>;
+    /**
+     * Mark as auto-increment (SQLite ROWID alias).
+     *
+     * @example
+     * const id = integer("id").primaryKey().autoIncrement();
+     */
+    autoIncrement(): IntegerColumnDef<S>;
+}
+/** A date column that stores a unix timestamp (milliseconds) in SQLite. Nullable in results unless `.defaultNow()` is called. */
+export interface DateColumnDef extends ColumnDef<Date, 'integer'> {
+    primaryKey(): DateColumnDef;
+    notNull(): DateColumnDef;
+    unique(): DateColumnDef;
+    default(value: Date): DateColumnDef;
+    defaultFn(fn: () => Date): DateColumnDef;
+    /**
+     * Use `Date.now()` as the default when the value is omitted during insert.
+     *
+     * @example
+     * const createdAt = date("created_at").defaultNow();
+     */
+    defaultNow(): DateColumnDefWithDefault;
+    /**
+     * Always set to `Date.now()` on update, regardless of the provided value.
+     *
+     * @example
+     * const updatedAt = date("updated_at").onUpdateTimestamp();
+     */
+    onUpdateTimestamp(): DateColumnDef;
+}
+/** A date column with a guaranteed default value, making it non-nullable in query results. */
+export interface DateColumnDefWithDefault extends DateColumnDef {
+    primaryKey(): DateColumnDefWithDefault;
+    notNull(): DateColumnDefWithDefault;
+    unique(): DateColumnDefWithDefault;
+    default(value: Date): DateColumnDefWithDefault;
+    defaultFn(fn: () => Date): DateColumnDefWithDefault;
+    defaultNow(): DateColumnDefWithDefault;
+    onUpdateTimestamp(): DateColumnDefWithDefault;
+}
+/**
+ * Create a text column.
+ *
+ * @example
+ * const name = text("name").notNull();
+ */
+export declare function text(name?: string): ColumnDef<string, 'text'>;
+/**
+ * Create an integer column.
+ *
+ * @example
+ * const id = integer("id").primaryKey().autoIncrement();
+ */
+export declare function integer(name?: string): IntegerColumnDef<'integer'>;
+/**
+ * Create a boolean column. Stores `0`/`1` in SQLite, exposed as `boolean` in TypeScript.
+ *
+ * @example
+ * const active = boolean("active").notNull().default(true);
+ */
+export declare function boolean(name?: string): ColumnDef<boolean, 'integer'>;
+/**
+ * Create a JSON column. Stores JSON text in SQLite, exposed as `T` in TypeScript.
+ *
+ * @example
+ * const meta = json<Record<string, unknown>>("meta").default({});
+ */
+export declare function json<T>(name?: string): ColumnDef<T, 'text'>;
+/**
+ * Create a date column. Stores a unix timestamp (milliseconds) in SQLite, exposed as `Date` in TypeScript.
+ *
+ * @example
+ * const createdAt = date("created_at").defaultNow().notNull();
+ */
+export declare function date(name?: string): DateColumnDef;
+/**
+ * Create a real (floating-point) column.
+ *
+ * @example
+ * const price = real("price").notNull();
+ */
+export declare function real(name?: string): ColumnDef<number, 'real'>;

package/dist/schema/table.d.ts

@@ -0,0 +1,74 @@
+import type { ColumnDef, DateColumnDef, DateColumnDefWithDefault } from './columns';
+/** A table definition mapping column names to their `ColumnDef`s. */
+export type TableDef<T> = T & {
+    readonly _: {
+        readonly name: string;
+    };
+};
+export declare function table<T extends Record<string, ColumnDef<any, any>>>(name: string, columns: T, indexFn?: (t: TableDef<T>) => IndexBuilder[]): TableDef<T>;
+/**
+ * Derive the row shape from a table's column definitions.
+ * DateColumnDef → Date | null (nullable unless defaultNow() was called)
+ * DateColumnDefWithDefault → Date (non-nullable, has a guaranteed default)
+ * All other columns → their _type as-is.
+ *
+ * Uses `infer C` to extract the column record from TableDef<T> so TypeScript
+ * evaluates the mapped type against the concrete columns, not the intersection.
+ * This produces cleaner hover info: { id: string; name: string } instead of
+ * Pick<InferRow<TableDef<{...}>>, ...>.
+ */
+export type InferRow<T extends TableDef<any>> = T extends TableDef<infer C> ? {
+    [K in keyof Omit<C, '_'>]: C[K] extends DateColumnDefWithDefault ? Date : C[K] extends DateColumnDef ? Date | null : C[K] extends ColumnDef<any, any> ? C[K]['__internal']['_type'] : never;
+} : never;
+/** The row type for inserts — columns with auto-defaults (integer, date) are optional. */
+export type InsertRow<T extends TableDef<any>> = {
+    [K in keyof Omit<T, '_'> as HasAutoDefault<T[K]> extends true ? never : K]: T[K] extends ColumnDef<any, any> ? T[K]['__internal']['_type'] : never;
+} & {
+    [K in keyof Omit<T, '_'> as HasAutoDefault<T[K]> extends true ? K : never]?: T[K] extends ColumnDef<any, any> ? T[K]['__internal']['_type'] : never;
+};
+/**
+ * Define a table with auto snake_case column names.
+ * Column names are inferred from object keys and converted to snake_case.
+ * Column constructors can be called without a name.
+ *
+ * @example
+ * const users = snakeCase.table("users", {
+ *   id: text().primaryKey(),
+ *   firstName: text(),
+ * });
+ */
+export declare function snakeCaseTable<T extends Record<string, ColumnDef<any, any>>>(tableName: string, columns: T, indexFn?: (t: TableDef<T>) => IndexBuilder[]): TableDef<T>;
+/** Provides `snakeCase.table()` for auto snake_case column naming. */
+export declare const snakeCase: {
+    table: typeof snakeCaseTable;
+};
+/** An index definition — used internally by the migration system. */
+export interface IndexDef {
+    name: string;
+    columns: string[];
+    unique: boolean;
+}
+/** Public builder returned by `index()` — chain `.on(columns)` then `.unique()`. */
+export interface IndexBuilder {
+    /** Add one or more columns to the index. */
+    on(...columns: ColumnDef<any, any>[]): IndexBuilder;
+    /** Mark the index as unique. */
+    unique(): IndexBuilder;
+}
+/**
+ * Create an index definition using a chainable API.
+ *
+ * @param name - The index name (will be used as-is in SQL)
+ * @returns An IndexBuilder — chain `.on(columns)` then `.unique()`
+ *
+ * @example
+ * const users = table("users", {
+ *   id: text("id").primaryKey(),
+ *   email: text("email"),
+ *   name: text("name"),
+ * }, (t) => [
+ *   index("idx_users_email").on(t.email).unique(),
+ *   index("idx_users_name").on(t.name),
+ * ]);
+ */
+export declare function index(name: string): IndexBuilderInternal;

package/dist/sqlite/introspect.d.ts

@@ -0,0 +1,19 @@
+import type { Database } from 'bun:sqlite';
+import type { SchemaState } from '../migration/types.js';
+/**
+ * Read the live database schema and return a SchemaState.
+ *
+ * This reads tables, columns, indexes, and foreign key references from
+ * the SQLite database using PRAGMAs.
+ *
+ * @param client - The bun:sqlite Database instance
+ * @returns SchemaState representing the live database schema
+ *
+ * @example
+ * import { Database } from "bun:sqlite";
+ * import { introspect } from "flint-orm/sqlite/introspect";
+ *
+ * const client = new Database("app.db");
+ * const state = introspect(client);
+ */
+export declare function introspect(client: Database): SchemaState;