@inflector/optima 1.0.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@inflector/optima",
+  "version": "1.0.0",
+  "module": "src/index.ts",
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "dev": "bun index.ts",
+    "build": "tsc"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@duckdb/node-api": "^1.4.1-r.5",
+    "zod": "^4.2.1"
+  }
+}

package/src/Qfluent.ts

@@ -0,0 +1,179 @@
+import type { DuckDBValue } from "@duckdb/node-api";
+import type { Infer } from "./schema";
+import type { Extension, OptimaTable, Where } from "./table";
+
+// --- Type Utilities ---
+export type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+export type SetFlag<State, Key extends keyof State> = {
+  [P in keyof State]: P extends Key ? true : State[P];
+};
+export type MapToFalse<T> = {
+  [K in keyof T]: false;
+};
+
+// Auto-generate initial "false" state for methods + the 'extended' flag
+export type InitialState<T> = {
+  [K in keyof T]: false;
+} & { extended: false };
+
+// --- Schema Definitions ---
+
+export type QueryMethods<TDef extends Record<string, any>> = {
+  limit: [n: number];
+  offset: [n: number];
+  orderBy: [col: keyof TDef | Array<keyof TDef>, dir?: "ASC" | "DESC"];
+  where: [w: Where<Infer<TDef>>];
+};
+
+export type QueryOneMethods<TDef extends Record<string, any>> = {
+  where: [w: Where<Infer<TDef>>];
+};
+
+// --- Fluent Interface Definitions ---
+
+// 1. Fluent Builder for Multiple Results (Array)
+export type FluentQueryBuilder<
+  TDef extends Record<string, any>,
+  Result,
+  // State includes standard methods + 'extended' flag
+  State extends Record<keyof QueryMethods<TDef> | "extended", boolean>
+> = {
+  // 1. Standard Methods (limit, where, etc.)
+  [K in keyof QueryMethods<TDef> as State[K] extends true ? never : K]: (
+    ...args: QueryMethods<TDef>[K]
+  ) => FluentQueryBuilder<TDef, Result, SetFlag<State, K>>;
+} & {
+    // 2. Extend Method (Conditional: Hide if State['extended'] is true)
+    [K in "extend" as State["extended"] extends true
+    ? never
+    : K]: <ExtTable extends OptimaTable<any>>(
+      table: ExtTable
+    ) => FluentQueryBuilder<
+      TDef,
+      Prettify<Result & Extension<TDef, ExtTable>>,
+      SetFlag<State, "extended"> // Mark extended as true
+    >;
+  } & PromiseLike<Result[]>;
+
+// 2. Fluent Builder for Single Result (One)
+export type FluentQueryBuilderOne<
+  TDef extends Record<string, any>,
+  Result,
+  State extends Record<keyof QueryOneMethods<TDef> | "extended", boolean>
+> = {
+  [K in keyof QueryOneMethods<TDef> as State[K] extends true ? never : K]: (
+    ...args: QueryOneMethods<TDef>[K]
+  ) => FluentQueryBuilderOne<TDef, Result, SetFlag<State, K>>;
+} & {
+    [K in "extend" as State["extended"] extends true
+    ? never
+    : K]: <ExtTable extends OptimaTable<any>>(
+      table: ExtTable
+    ) => FluentQueryBuilderOne<
+      TDef,
+      Prettify<Result & Extension<TDef, ExtTable>>,
+      SetFlag<State, "extended">
+    >;
+  } & PromiseLike<Result | undefined>;
+
+// --- Implementation ---
+
+export const createProxyHandler = (
+  table: OptimaTable<any>,
+  config: any,
+  isSingleResult: boolean
+) => {
+  return {
+    get(target: any, prop: string | symbol) {
+      // 1. Handle Promise Execution (.then)
+      if (prop === "then") {
+        return async (
+          resolve: (value: any) => void,
+          reject: (reason: any) => void
+        ) => {
+          const tableAny = table as any;
+          try {
+            const { sql } = tableAny.BuildSelect(tableAny["Name"], config);
+            const rawResult: Record<string, DuckDBValue>[] = await (
+              await tableAny.Connection.run(sql)
+            ).getRowObjects();
+            const formatted = tableAny.FormatOut(rawResult);
+
+            if (isSingleResult) {
+              const val = formatted.length > 0 ? formatted[0] : undefined;
+              resolve(val);
+            } else {
+              resolve(formatted);
+            }
+          } catch (e) {
+            reject(e);
+          }
+        };
+      }
+
+      // 2. Handle 'extend'
+      if (prop === "extend") {
+        return (extTable: OptimaTable<any>) => {
+          config.extend = config.extend || [];
+
+          // Optional Runtime Safety: Prevent adding the exact same table instance twice
+          // (Even though types now prevent calling extend() twice on the same chain)
+          if (!config.extend.includes(extTable)) {
+            config.extend.push(extTable);
+          }
+
+          return new Proxy(
+            target,
+            createProxyHandler(table, config, isSingleResult)
+          );
+        };
+      }
+
+      // 3. Handle Standard Schema Methods
+      return (...args: any[]) => {
+        if (args.length === 1) {
+          config[prop as string] = args[0];
+        } else if (args.length > 1) {
+          config[prop as string] = args;
+        } else {
+          config[prop as string] = true;
+        }
+
+        return new Proxy(
+          target,
+          createProxyHandler(table, config, isSingleResult)
+        );
+      };
+    },
+  };
+};
+
+// --- Factory Functions ---
+
+export function createQueryBuilder<TDef extends Record<string, any>, Result>(
+  table: OptimaTable<TDef>,
+  initialConfig: any = {}
+): FluentQueryBuilder<TDef, Result, InitialState<QueryMethods<TDef>>> {
+  const dummyState = {};
+  // The InitialState type ensures 'extended' starts as false
+  return new Proxy(
+    dummyState,
+    createProxyHandler(table, initialConfig, false)
+  ) as any;
+}
+
+export function createQueryBuilderOne<TDef extends Record<string, any>, Result>(
+  table: OptimaTable<TDef>,
+  initialConfig: any = {}
+): FluentQueryBuilderOne<TDef, Result, InitialState<QueryOneMethods<TDef>>> {
+  const config = { ...initialConfig, limit: 1 };
+  const dummyState = {};
+
+  return new Proxy(
+    dummyState,
+    createProxyHandler(table, config, true)
+  ) as any;
+}

package/src/database.ts

@@ -0,0 +1,284 @@
+import { DuckDBConnection, DuckDBInstance } from "@duckdb/node-api";
+import { OptimaTable } from "./table";
+
+// -- Types --
+type DBRow = Record<string, unknown>;
+type SchemaConfig = Record<string, any>;
+
+export class OptimaDB<T extends Record<string, OptimaTable>> {
+  private instance: DuckDBInstance;
+  private connection: DuckDBConnection;
+  public Tables: T;
+
+  constructor(
+    instance: DuckDBInstance,
+    connection: DuckDBConnection,
+    tables: T
+  ) {
+    this.instance = instance;
+    this.connection = connection;
+    this.Tables = tables;
+  }
+
+  /**
+   * Initializes the database, connects, detects schema changes, 
+   * runs migrations, and returns the DB instance.
+   */
+  static async Open<TSchema extends SchemaConfig>(
+    name: string = ":memory:",
+    schema: TSchema,
+    options?: { MemoryLimit?: string; ThreadCount?: number }
+  ): Promise<OptimaDB<{ [K in keyof TSchema]: OptimaTable<TSchema[K]> }>> {
+    const instance = await DuckDBInstance.create(name);
+    const connection = await instance.connect();
+
+    // 1. Apply Options
+    if (options?.MemoryLimit) {
+      await connection.run(`SET memory_limit = '${options.MemoryLimit}';`);
+    }
+    if (options?.ThreadCount) {
+      await connection.run(`SET threads = ${options.ThreadCount};`);
+    }
+
+    // 2. Auto-Migration
+    const existingTables = await (await connection.run(`SELECT * from duckdb_tables`)).getRowObjects();
+    const cleanSchema = SchemaMigrator.transformSchema(schema);
+    const migrationSQL = SchemaMigrator.generateSQL(existingTables, cleanSchema);
+
+    if (migrationSQL.length > 0) {
+      console.log(`[OptimaDB] Applying ${migrationSQL.length} migrations...`);
+      // Run migrations in a transaction to ensure safety
+      await connection.run("BEGIN TRANSACTION;");
+      try {
+        for (const sql of migrationSQL) {
+          await connection.run(sql);
+        }
+        await connection.run("COMMIT;");
+      } catch (err) {
+        await connection.run("ROLLBACK;");
+        console.error("[OptimaDB] Migration failed, rolling back.", err);
+        throw err;
+      }
+    }
+
+    // 3. Initialize Table Wrappers
+    const tables = {} as { [K in keyof TSchema]: OptimaTable<TSchema[K]> };
+    for (const key of Object.keys(schema) as Array<keyof TSchema>) {
+      tables[key] = await OptimaTable.create<TSchema[typeof key]>(
+        key as string,
+        schema[key],
+        connection
+      );
+    }
+
+    return new OptimaDB(instance, connection, tables);
+  }
+
+  /**
+   * Executes a raw SQL query and returns rows as objects.
+   */
+  async execute(sql: string): Promise<DBRow[]> {
+    return (await this.connection.run(sql)).getRowObjects();
+  }
+
+  async getTables(): Promise<string[]> {
+    const result = await this.execute("PRAGMA show_tables;");
+    return result.map((t: any) => t.name);
+  }
+
+  async getDiskSize(): Promise<unknown> {
+    const result = await this.execute("PRAGMA database_size;");
+    return result[0];
+  }
+
+  /**
+   * Runs a function within a transaction. 
+   * Re-throws error after rollback so caller handles logic failure.
+   */
+  async transaction<R>(fn: () => Promise<R>): Promise<R> {
+    await this.connection.run("BEGIN TRANSACTION;");
+    try {
+      const result = await fn();
+      await this.connection.run("COMMIT;");
+      return result;
+    } catch (e) {
+      await this.connection.run("ROLLBACK;");
+      throw e;
+    }
+  }
+}
+
+/**
+ * ------------------------------------------------------------------
+ * INTERNAL MIGRATION LOGIC
+ * Encapsulated to keep the main class clean.
+ * ------------------------------------------------------------------
+ */
+class SchemaMigrator {
+  /**
+   * Transforms the complex Module/ColumnImpl schema into a simple config object.
+   */
+  static transformSchema(schemaObject: SchemaConfig) {
+    const cleanSchema: Record<string, Record<string, any>> = {};
+
+    for (const [tableName, tableDef] of Object.entries(schemaObject)) {
+      if (typeof tableDef !== "object" || tableDef === null) continue;
+
+      const realTableName = tableDef.__tableName || tableName;
+      cleanSchema[realTableName] = {};
+
+      for (const [colName, colImpl] of Object.entries(tableDef)) {
+        if (colName.startsWith("__")) continue; // Skip metadata
+
+        // @ts-ignore - Assuming colImpl structure based on input
+        if (colImpl?.config) {
+          // @ts-ignore
+          const config = { ...colImpl.config };
+          
+          // Handle STRUCT merging
+          if (config.SQlType === "STRUCT" && config.STRUCTType) {
+            config.SQlType = config.STRUCTType;
+          }
+          cleanSchema[realTableName][colName] = config;
+        }
+      }
+    }
+    return cleanSchema;
+  }
+
+  /**
+   * Generates SQL statements to migrate DB from Current -> Desired state.
+   */
+  static generateSQL(existingTablesRaw: any[], desiredSchema: Record<string, any>) {
+    const currentSchema = this.parseDuckDBTableSQL(existingTablesRaw);
+    const steps: string[] = [];
+
+    for (const [tableName, fields] of Object.entries(desiredSchema)) {
+      
+      // 1. CREATE TABLE
+      if (!currentSchema[tableName]) {
+        const fieldDefs = Object.entries(fields).map(([colName, config]: [string, any]) => {
+          let def = `"${colName}" ${config.SQlType}`;
+          if (config.primaryKey) def += " PRIMARY KEY";
+          if (config.notnull) def += " NOT NULL";
+          return def;
+        });
+        steps.push(`CREATE TABLE ${tableName} (${fieldDefs.join(", ")});`);
+        continue;
+      }
+
+      const currentTableCols = currentSchema[tableName];
+
+      for (const [colName, config] of Object.entries(fields) as [string, any][]) {
+        
+        // 2. ADD COLUMN
+        if (!currentTableCols[colName]) {
+          let def = `${config.SQlType}`;
+          // If adding NOT NULL to existing table, we need a default value
+          if (config.notnull) {
+            def += ` DEFAULT ${this.getDefaultValueForType(config.SQlType)}`;
+          }
+          steps.push(`ALTER TABLE ${tableName} ADD COLUMN "${colName}" ${def};`);
+
+          // Enforce strict constraint after adding (if supported by version, else implied by definition)
+          if (config.notnull) {
+            steps.push(`ALTER TABLE ${tableName} ALTER "${colName}" SET NOT NULL;`);
+          }
+          continue;
+        }
+
+        // 3. ALTER COLUMN (Type or Constraints)
+        const currentCol = currentTableCols[colName];
+        const normCurrentType = currentCol.type.replace(/\s+/g, "").toUpperCase();
+        const normNewType = config.SQlType.replace(/\s+/g, "").toUpperCase();
+
+        // 3a. Type Mismatch
+        // We skip complex struct comparison here to avoid false positives on spacing
+        if (normCurrentType !== normNewType && !normNewType.startsWith("STRUCT")) {
+          steps.push(`ALTER TABLE ${tableName} ALTER "${colName}" TYPE ${config.SQlType};`);
+        }
+
+        // 3b. Not Null Mismatch
+        const desiredNotNull = !!config.notnull;
+        if (desiredNotNull !== currentCol.isNotNull) {
+          if (desiredNotNull) {
+             steps.push(`ALTER TABLE ${tableName} ALTER "${colName}" SET NOT NULL;`);
+          } else {
+             steps.push(`ALTER TABLE ${tableName} ALTER "${colName}" DROP NOT NULL;`);
+          }
+        }
+      }
+    }
+    return steps;
+  }
+
+  /**
+   * Parses raw "CREATE TABLE" SQL from DuckDB into a usable map.
+   */
+  private static parseDuckDBTableSQL(existingTables: any[]) {
+    const schemaMap: Record<string, Record<string, { type: string; isNotNull: boolean; isPrimaryKey: boolean }>> = {};
+
+    existingTables.forEach((table) => {
+      const match = table.sql.match(/CREATE TABLE "?\w+"?\s*\((.*)\);/s);
+      if (!match) return;
+
+      const columnBody = match[1];
+      const columns: Record<string, any> = {};
+
+      let depth = 0;
+      let currentChunk = "";
+
+      for (let i = 0; i < columnBody.length; i++) {
+        const char = columnBody[i];
+        if (char === "(") depth++;
+        if (char === ")") depth--;
+
+        if (char === "," && depth === 0) {
+          this.processColumnLine(currentChunk, columns);
+          currentChunk = "";
+        } else {
+          currentChunk += char;
+        }
+      }
+      if (currentChunk.trim()) this.processColumnLine(currentChunk, columns);
+
+      schemaMap[table.table_name] = columns;
+    });
+
+    return schemaMap;
+  }
+
+  private static processColumnLine(line: string, columnMap: Record<string, any>) {
+    const parts = line.trim().match(/^("?[\w]+"?)\s+(.*)$/);
+    if (!parts) return;
+
+    const name = parts[1]?.replace(/"/g, "");
+    const definition = parts[2];
+    const upDef = definition?.toUpperCase();
+
+    let type = definition?.split(" ")[0];
+    if (upDef?.startsWith("STRUCT")) {
+      type = definition; // Simplification: capture full struct definition
+    }
+
+    if (name !== undefined) {
+      columnMap[name] = {
+        type: type,
+        isNotNull: upDef?.includes("NOT NULL") ?? false,
+        isPrimaryKey: upDef?.includes("PRIMARY KEY") ?? false,
+      };
+    }
+  }
+
+  /**
+   * Returns a safe default value for a given SQL type.
+   * Required when adding NOT NULL columns to existing tables.
+   */
+  private static getDefaultValueForType(type: string): string {
+    const t = type.toUpperCase();
+    if (t.includes("INT") || t.includes("FLOAT") || t.includes("DECIMAL") || t.includes("DOUBLE")) return "0";
+    if (t.includes("BOOL")) return "FALSE";
+    if (t.includes("STRUCT") || t.includes("MAP") || t.includes("LIST")) return "NULL"; // Complex types usually default to NULL
+    return "''"; // VARCHAR, TEXT, etc.
+  }
+}

package/src/fluent.ts

@@ -0,0 +1,55 @@
+export type SetFlag<State, Key extends keyof State> = {
+  [P in keyof State]: P extends Key ? true : State[P];
+};
+type MapToFalse<T> = {
+  [K in keyof T]: false;
+};
+type FluentStep<
+  Schema,
+  State extends { [K in keyof Schema]: boolean | unknown },
+  Result
+> = {
+  [K in keyof Schema as State[K] extends true
+    ? never
+    : K]: Schema[K] extends boolean
+    ? () => FluentStep<Schema, SetFlag<State, K>, Result> 
+    : Schema[K] extends any[]
+    ? (...args: Schema[K]) => FluentStep<Schema, SetFlag<State, K>, Result> 
+    : (arg: Schema[K]) => FluentStep<Schema, SetFlag<State, K>, Result>;
+} & PromiseLike<Result>;
+
+export function createFluentBuilder<Schema, R = Schema>(
+  onBuild?: (data: Schema) => R | Promise<R>
+): FluentStep<Schema, MapToFalse<Schema>, R> {
+  const data: any = {};
+
+  const handler: ProxyHandler<any> = {
+    get(target, prop) {
+      if (prop === "then") {
+        return (resolve: any, reject: any) => {
+          const result = onBuild ? onBuild(target) : target;
+          Promise.resolve(result).then(resolve, reject);
+        };
+      }
+
+      return (...args: any[]) => {
+        // 1. No Args -> True (Flag)
+        if (args.length === 0) {
+          target[prop as string] = true;
+        }
+        // 2. One Arg -> Store value
+        else if (args.length === 1) {
+          target[prop as string] = args[0];
+        }
+        // 3. Multiple Args -> Store as Array/Tuple
+        else {
+          target[prop as string] = args;
+        }
+
+        return new Proxy(target, handler);
+      };
+    },
+  };
+
+  return new Proxy(data, handler);
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from "./database";
+export * from "./schema";
+export {
+  eq, ne, gt, gte, lt, lte,
+  inOp, notIn,
+  between, notBetween,
+  is, isNot,
+  like, notLike,
+  startsWith, endsWith,
+  contains,
+  regexp, notRegexp,
+  cond,
+  type ConditionBuilder
+} from "./table";