@ricsam/formula-engine 0.0.21 → 0.0.22

package/dist/mjs/core/{api → schema}/cell-orm.mjs

@@ -1,4 +1,4 @@
-// src/core/api/cell-orm.ts
+// src/core/schema/cell-orm.ts
 class CellOrm {
   engine;
   cellAddress;
@@ -46,4 +46,4 @@ export {
   CellOrm
 };
 
-//# debugId=A0736D945C92E6BF64756E2164756E21
+//# debugId=7C807D7F54F7BB5564756E2164756E21

package/dist/mjs/core/{api → schema}/cell-orm.mjs.map

@@ -1,10 +1,10 @@
 {
   "version": 3,
-  "sources": ["../../../../src/core/api/cell-orm.ts"],
+  "sources": ["../../../../src/core/schema/cell-orm.ts"],
   "sourcesContent": [
     "/**\n * CellOrm - Object-Relational Mapping for single cell data\n *\n * Provides read/write operations for a single cell with type-safe access.\n * Used as the `this` context for custom cell API methods.\n */\n\nimport type { CellAddress, SerializedCellValue } from \"../types.mjs\";\nimport type { FormulaEngine } from \"../engine.mjs\";\n\nexport type CellParseFunction<TCellMetadata, TValue> = (\n  value: unknown,\n  metadata: TCellMetadata\n) => TValue;\n\nexport class CellOrm<TValue, TCellMetadata = unknown> {\n  constructor(\n    private engine: FormulaEngine<any, any>,\n    private cellAddress: CellAddress,\n    private parser: CellParseFunction<TCellMetadata, TValue>,\n    private namespace: string\n  ) {}\n\n  /**\n   * Read the cell value and parse it using the schema's parse function\n   */\n  read(): TValue {\n    const value = this.engine.getCellValue(this.cellAddress);\n    const metadata = this.engine.getCellMetadata(this.cellAddress) as TCellMetadata;\n    return this.parser(value, metadata);\n  }\n\n  /**\n   * Write a value to the cell\n   * The value should be the parsed type - it will be converted to a serializable value\n   */\n  write(value: TValue): void {\n    // Convert TValue to SerializedCellValue\n    let serializedValue: SerializedCellValue;\n\n    if (\n      typeof value === \"string\" ||\n      typeof value === \"number\" ||\n      typeof value === \"boolean\"\n    ) {\n      serializedValue = value;\n    } else if (value === null || value === undefined) {\n      serializedValue = undefined;\n    } else if (typeof value === \"object\") {\n      // For objects, we need to extract the actual cell value\n      // This assumes the parsed type might be an object with a 'value' property\n      const obj = value as Record<string, unknown>;\n      if (\"value\" in obj) {\n        const innerValue = obj.value;\n        if (\n          typeof innerValue === \"string\" ||\n          typeof innerValue === \"number\" ||\n          typeof innerValue === \"boolean\"\n        ) {\n          serializedValue = innerValue;\n        } else {\n          serializedValue = String(innerValue);\n        }\n      } else {\n        // Fallback: convert to string\n        serializedValue = JSON.stringify(value);\n      }\n    } else {\n      serializedValue = String(value);\n    }\n\n    this.engine.setCellContent(this.cellAddress, serializedValue);\n  }\n\n  /**\n   * Get the cell address\n   */\n  getAddress(): CellAddress {\n    return { ...this.cellAddress };\n  }\n}\n"
   ],
   "mappings": ";AAeO,MAAM,QAAyC;AAAA,EAE1C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAJV,WAAW,CACD,QACA,aACA,QACA,WACR;AAAA,IAJQ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA;AAAA,EAMV,IAAI,GAAW;AAAA,IACb,MAAM,QAAQ,KAAK,OAAO,aAAa,KAAK,WAAW;AAAA,IACvD,MAAM,WAAW,KAAK,OAAO,gBAAgB,KAAK,WAAW;AAAA,IAC7D,OAAO,KAAK,OAAO,OAAO,QAAQ;AAAA;AAAA,EAOpC,KAAK,CAAC,OAAqB;AAAA,IAEzB,IAAI;AAAA,IAEJ,IACE,OAAO,UAAU,YACjB,OAAO,UAAU,YACjB,OAAO,UAAU,WACjB;AAAA,MACA,kBAAkB;AAAA,IACpB,EAAO,SAAI,UAAU,QAAQ,UAAU,WAAW;AAAA,MAChD,kBAAkB;AAAA,IACpB,EAAO,SAAI,OAAO,UAAU,UAAU;AAAA,MAGpC,MAAM,MAAM;AAAA,MACZ,IAAI,WAAW,KAAK;AAAA,QAClB,MAAM,aAAa,IAAI;AAAA,QACvB,IACE,OAAO,eAAe,YACtB,OAAO,eAAe,YACtB,OAAO,eAAe,WACtB;AAAA,UACA,kBAAkB;AAAA,QACpB,EAAO;AAAA,UACL,kBAAkB,OAAO,UAAU;AAAA;AAAA,MAEvC,EAAO;AAAA,QAEL,kBAAkB,KAAK,UAAU,KAAK;AAAA;AAAA,IAE1C,EAAO;AAAA,MACL,kBAAkB,OAAO,KAAK;AAAA;AAAA,IAGhC,KAAK,OAAO,eAAe,KAAK,aAAa,eAAe;AAAA;AAAA,EAM9D,UAAU,GAAgB;AAAA,IACxB,OAAO,KAAK,KAAK,YAAY;AAAA;AAEjC;",
-  "debugId": "A0736D945C92E6BF64756E2164756E21",
+  "debugId": "7C807D7F54F7BB5564756E2164756E21",
   "names": []
 }

package/dist/mjs/core/{api/api-builder.mjs → schema/schema-builder.mjs}

@@ -1,27 +1,27 @@
-// src/core/api/api-builder.ts
+// src/core/schema/schema-builder.ts
 import { TableOrm } from "./table-orm.mjs";
 import { CellOrm } from "./cell-orm.mjs";
-function buildApiFromDeclaration(engine, declaration, schemaManager) {
-  const api = {};
+function buildSchemaFromDeclaration(engine, declaration, schemaManager) {
+  const schema = {};
   for (const [namespace, def] of Object.entries(declaration)) {
     if (def.type === "table") {
-      api[namespace] = buildTableApi(engine, namespace, def, schemaManager);
+      schema[namespace] = buildTableSchema(engine, namespace, def, schemaManager);
     } else if (def.type === "cell") {
-      api[namespace] = buildCellApi(engine, namespace, def, schemaManager);
+      schema[namespace] = buildCellSchema(engine, namespace, def, schemaManager);
     }
   }
-  return api;
+  return schema;
 }
-function buildTableApi(engine, namespace, def, schemaManager) {
+function buildTableSchema(engine, namespace, def, schemaManager) {
   schemaManager.registerTableSchema(namespace, def.workbookName, def.tableName, def.headers);
   return new TableOrm(engine, def.workbookName, def.tableName, def.headers, namespace);
 }
-function buildCellApi(engine, namespace, def, schemaManager) {
+function buildCellSchema(engine, namespace, def, schemaManager) {
   schemaManager.registerCellSchema(namespace, def.cellAddress, def.parse);
   return new CellOrm(engine, def.cellAddress, def.parse, namespace);
 }
 export {
-  buildApiFromDeclaration
+  buildSchemaFromDeclaration
 };
 
-//# debugId=3B353A0CD99B342764756E2164756E21
+//# debugId=362026195AB1C12164756E2164756E21

package/dist/mjs/core/schema/schema-builder.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/core/schema/schema-builder.ts"],
+  "sourcesContent": [
+    "/**\n * Schema Builder - Constructs the working schema from declarations\n *\n * This module is responsible for creating the actual working schema\n * from the schema declarations when attached to a FormulaEngine.\n */\n\nimport type { FormulaEngine } from \"../engine.mjs\";\nimport type { SchemaDeclaration, TableSchemaDefinition, CellSchemaDefinition, Schema } from \"./schema.mjs\";\nimport { TableOrm } from \"./table-orm.mjs\";\nimport { CellOrm } from \"./cell-orm.mjs\";\nimport type { SchemaManager } from \"../managers/schema-manager.mjs\";\n\n/**\n * Build the working schema surface from declarations\n *\n * This creates TableOrm and CellOrm instances for each declared schema\n * and returns them directly.\n */\nexport function buildSchemaFromDeclaration(\n  engine: FormulaEngine<any, any>,\n  declaration: SchemaDeclaration,\n  schemaManager: SchemaManager\n): Schema {\n  const schema: Schema = {};\n\n  for (const [namespace, def] of Object.entries(declaration)) {\n    if (def.type === \"table\") {\n      schema[namespace] = buildTableSchema(engine, namespace, def, schemaManager);\n    } else if (def.type === \"cell\") {\n      schema[namespace] = buildCellSchema(engine, namespace, def, schemaManager);\n    }\n  }\n\n  return schema;\n}\n\n/**\n * Build schema for a table schema - returns TableOrm instance directly\n */\nfunction buildTableSchema(\n  engine: FormulaEngine<any, any>,\n  namespace: string,\n  def: TableSchemaDefinition,\n  schemaManager: SchemaManager\n): TableOrm<any> {\n  // Register the schema with the schema manager\n  schemaManager.registerTableSchema(\n    namespace,\n    def.workbookName,\n    def.tableName,\n    def.headers\n  );\n\n  // Create and return the ORM instance directly\n  return new TableOrm(\n    engine,\n    def.workbookName,\n    def.tableName,\n    def.headers,\n    namespace\n  );\n}\n\n/**\n * Build schema for a cell schema - returns CellOrm instance directly\n */\nfunction buildCellSchema(\n  engine: FormulaEngine<any, any>,\n  namespace: string,\n  def: CellSchemaDefinition,\n  schemaManager: SchemaManager\n): CellOrm<any> {\n  // Register the schema with the schema manager\n  schemaManager.registerCellSchema(namespace, def.cellAddress, def.parse);\n\n  // Create and return the ORM instance directly\n  return new CellOrm(engine, def.cellAddress, def.parse, namespace);\n}\n"
+  ],
+  "mappings": ";AASA;AACA;AASO,SAAS,0BAA0B,CACxC,QACA,aACA,eACQ;AAAA,EACR,MAAM,SAAiB,CAAC;AAAA,EAExB,YAAY,WAAW,QAAQ,OAAO,QAAQ,WAAW,GAAG;AAAA,IAC1D,IAAI,IAAI,SAAS,SAAS;AAAA,MACxB,OAAO,aAAa,iBAAiB,QAAQ,WAAW,KAAK,aAAa;AAAA,IAC5E,EAAO,SAAI,IAAI,SAAS,QAAQ;AAAA,MAC9B,OAAO,aAAa,gBAAgB,QAAQ,WAAW,KAAK,aAAa;AAAA,IAC3E;AAAA,EACF;AAAA,EAEA,OAAO;AAAA;AAMT,SAAS,gBAAgB,CACvB,QACA,WACA,KACA,eACe;AAAA,EAEf,cAAc,oBACZ,WACA,IAAI,cACJ,IAAI,WACJ,IAAI,OACN;AAAA,EAGA,OAAO,IAAI,SACT,QACA,IAAI,cACJ,IAAI,WACJ,IAAI,SACJ,SACF;AAAA;AAMF,SAAS,eAAe,CACtB,QACA,WACA,KACA,eACc;AAAA,EAEd,cAAc,mBAAmB,WAAW,IAAI,aAAa,IAAI,KAAK;AAAA,EAGtE,OAAO,IAAI,QAAQ,QAAQ,IAAI,aAAa,IAAI,OAAO,SAAS;AAAA;",
+  "debugId": "362026195AB1C12164756E2164756E21",
+  "names": []
+}

package/dist/mjs/core/{api/api-helpers.mjs → schema/schema-helpers.mjs}

@@ -1,4 +1,4 @@
-// src/core/api/api-helpers.ts
+// src/core/schema/schema-helpers.ts
 function rowToObject(engine, table, rowIndex, headers, getCellMetadata) {
   const result = {};
   for (const [columnName, header] of Object.entries(headers)) {
@@ -158,4 +158,4 @@ export {
   getNextEmptyRow
 };
 
-//# debugId=0AEE3F3D29B7684464756E2164756E21
+//# debugId=107165D9A940C78E64756E2164756E21

package/dist/mjs/core/schema/schema-helpers.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/core/schema/schema-helpers.ts"],
+  "sourcesContent": [
+    "/**\n * Schema Helper utilities for row/object conversion and filtering\n */\n\nimport type { CellAddress, SerializedCellValue, TableDefinition } from \"../types.mjs\";\nimport type { FormulaEngine } from \"../engine.mjs\";\n\nexport type ParseFunction<TCellMetadata = unknown> = (\n  value: unknown,\n  metadata: TCellMetadata\n) => unknown;\n\nexport type TableSchemaHeaders<TCellMetadata = unknown> = Record<\n  string,\n  {\n    parse: ParseFunction<TCellMetadata>;\n    index: number;\n  }\n>;\n\n/**\n * Convert a spreadsheet row to a typed object using header parsers\n */\nexport function rowToObject<TItem extends Record<string, unknown>>(\n  engine: FormulaEngine<any, any>,\n  table: TableDefinition,\n  rowIndex: number,\n  headers: TableSchemaHeaders,\n  getCellMetadata?: (cell: CellAddress) => unknown\n): TItem {\n  const result: Record<string, unknown> = {};\n\n  for (const [columnName, header] of Object.entries(headers)) {\n    const cellAddress: CellAddress = {\n      workbookName: table.workbookName,\n      sheetName: table.sheetName,\n      colIndex: table.start.colIndex + header.index,\n      rowIndex,\n    };\n\n    const value = engine.getCellValue(cellAddress);\n    const metadata = getCellMetadata ? getCellMetadata(cellAddress) : undefined;\n\n    // Parse the value using the column's parse function\n    result[columnName] = header.parse(value, metadata);\n  }\n\n  return result as TItem;\n}\n\n/**\n * Convert a typed object to cell values based on headers\n */\nexport function objectToRowValues<TItem extends Record<string, unknown>>(\n  obj: TItem,\n  headers: TableSchemaHeaders\n): Map<number, SerializedCellValue> {\n  const values = new Map<number, SerializedCellValue>();\n\n  for (const [columnName, header] of Object.entries(headers)) {\n    if (columnName in obj) {\n      const value = obj[columnName];\n      // Convert to serializable value\n      if (\n        typeof value === \"string\" ||\n        typeof value === \"number\" ||\n        typeof value === \"boolean\"\n      ) {\n        values.set(header.index, value);\n      } else if (value === null || value === undefined) {\n        values.set(header.index, undefined);\n      } else {\n        // For complex types, convert to string\n        values.set(header.index, String(value));\n      }\n    }\n  }\n\n  return values;\n}\n\n/**\n * Check if an object matches a filter predicate\n */\nexport function matchesFilter<TItem extends Record<string, unknown>>(\n  item: TItem,\n  filter: Partial<TItem>\n): boolean {\n  for (const [key, value] of Object.entries(filter)) {\n    if (item[key] !== value) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/**\n * Get the number of data rows in a table (excluding header)\n */\nexport function getTableRowCount(\n  engine: FormulaEngine<any, any>,\n  table: TableDefinition\n): number {\n  if (table.endRow.type === \"infinity\") {\n    // For infinite tables, count non-empty rows\n    // Start from data row (after header)\n    let count = 0;\n    let emptyRowStreak = 0;\n    const maxEmptyRows = 10; // Stop after 10 consecutive empty rows\n\n    for (let row = table.start.rowIndex + 1; emptyRowStreak < maxEmptyRows; row++) {\n      let hasContent = false;\n\n      for (let col = 0; col < table.headers.size; col++) {\n        const cellAddress: CellAddress = {\n          workbookName: table.workbookName,\n          sheetName: table.sheetName,\n          colIndex: table.start.colIndex + col,\n          rowIndex: row,\n        };\n\n        const value = engine.getCellValue(cellAddress);\n        if (value !== \"\" && value !== undefined) {\n          hasContent = true;\n          break;\n        }\n      }\n\n      if (hasContent) {\n        count++;\n        emptyRowStreak = 0;\n      } else {\n        emptyRowStreak++;\n      }\n    }\n\n    return count;\n  } else {\n    // For finite tables, calculate from endRow\n    return table.endRow.value - table.start.rowIndex;\n  }\n}\n\n/**\n * Get the next empty row index for appending data\n */\nexport function getNextEmptyRow(\n  engine: FormulaEngine<any, any>,\n  table: TableDefinition\n): number {\n  const dataStartRow = table.start.rowIndex + 1;\n\n  if (table.endRow.type === \"infinity\") {\n    // Find first empty row\n    let emptyRowStreak = 0;\n    const maxEmptyRows = 10;\n\n    for (let row = dataStartRow; ; row++) {\n      let hasContent = false;\n\n      for (let col = 0; col < table.headers.size; col++) {\n        const cellAddress: CellAddress = {\n          workbookName: table.workbookName,\n          sheetName: table.sheetName,\n          colIndex: table.start.colIndex + col,\n          rowIndex: row,\n        };\n\n        const value = engine.getCellValue(cellAddress);\n        if (value !== \"\" && value !== undefined) {\n          hasContent = true;\n          break;\n        }\n      }\n\n      if (!hasContent) {\n        return row;\n      }\n\n      emptyRowStreak = hasContent ? 0 : emptyRowStreak + 1;\n      if (emptyRowStreak >= maxEmptyRows) {\n        return row - maxEmptyRows + 1;\n      }\n    }\n  } else {\n    // For finite tables, return the row after the last data row\n    return table.endRow.value + 1;\n  }\n}\n\n/**\n * Iterate over all data rows in a table\n */\nexport function* iterateTableRows(\n  engine: FormulaEngine<any, any>,\n  table: TableDefinition\n): Generator<{ rowIndex: number; isEmpty: boolean }> {\n  const dataStartRow = table.start.rowIndex + 1;\n\n  if (table.endRow.type === \"infinity\") {\n    let emptyRowStreak = 0;\n    const maxEmptyRows = 10;\n\n    for (let row = dataStartRow; emptyRowStreak < maxEmptyRows; row++) {\n      let hasContent = false;\n\n      for (let col = 0; col < table.headers.size; col++) {\n        const cellAddress: CellAddress = {\n          workbookName: table.workbookName,\n          sheetName: table.sheetName,\n          colIndex: table.start.colIndex + col,\n          rowIndex: row,\n        };\n\n        const value = engine.getCellValue(cellAddress);\n        if (value !== \"\" && value !== undefined) {\n          hasContent = true;\n          break;\n        }\n      }\n\n      if (hasContent) {\n        emptyRowStreak = 0;\n        yield { rowIndex: row, isEmpty: false };\n      } else {\n        emptyRowStreak++;\n        // Don't yield empty rows at the end\n      }\n    }\n  } else {\n    for (let row = dataStartRow; row <= table.endRow.value; row++) {\n      let hasContent = false;\n\n      for (let col = 0; col < table.headers.size; col++) {\n        const cellAddress: CellAddress = {\n          workbookName: table.workbookName,\n          sheetName: table.sheetName,\n          colIndex: table.start.colIndex + col,\n          rowIndex: row,\n        };\n\n        const value = engine.getCellValue(cellAddress);\n        if (value !== \"\" && value !== undefined) {\n          hasContent = true;\n          break;\n        }\n      }\n\n      yield { rowIndex: row, isEmpty: !hasContent };\n    }\n  }\n}\n\n"
+  ],
+  "mappings": "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",
+  "debugId": "107165D9A940C78E64756E2164756E21",
+  "names": []
+}

package/dist/mjs/core/{api/api.mjs → schema/schema.mjs}

@@ -1,8 +1,8 @@
-// src/core/api/api.ts
-function defineApi() {
+// src/core/schema/schema.ts
+function defineSchema() {
   const declaration = {};
   const builder = {
-    addTableApi(namespace, address, headers) {
+    addTableSchema(namespace, address, headers) {
       declaration[namespace] = {
         type: "table",
         tableName: address.tableName,
@@ -11,7 +11,7 @@ function defineApi() {
       };
       return builder;
     },
-    addCellApi(namespace, cellAddress, parse) {
+    addCellSchema(namespace, cellAddress, parse) {
       declaration[namespace] = {
         type: "cell",
         cellAddress,
@@ -19,15 +19,13 @@ function defineApi() {
       };
       return builder;
     },
-    api: undefined,
+    schema: undefined,
     declaration
   };
   return builder;
 }
-var createApi = defineApi;
 export {
-  defineApi,
-  createApi
+  defineSchema
 };
 
-//# debugId=6D6EFC9F69FE55CC64756E2164756E21
+//# debugId=DD0716E0FB48113C64756E2164756E21

package/dist/mjs/core/schema/schema.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/core/schema/schema.ts"],
+  "sourcesContent": [
+    "import type { CellAddress } from \"../types.mjs\";\n\n/**\n * Define a schema for the FormulaEngine.\n *\n * The returned object contains:\n * - `declaration`: The schema definitions for tables and cells\n * - `schema`: A type-only placeholder (undefined at runtime) for TypeScript inference\n *\n * The actual working schema is only available through `engine.schema` after\n * attaching the definition to a FormulaEngine instance.\n *\n * @example\n * ```typescript\n * const mySchema = defineSchema<CellMetadata>()\n *   .addTableSchema(\"users\", { workbookName: \"wb1\", tableName: \"users\" }, headers)\n *   .addCellSchema(\"config\", cellAddress, parse);\n *\n * const engine = new FormulaEngine(mySchema);\n * engine.schema.users.findWhere({ id: 1 }); // Works!\n * engine.schema.config.read(); // Works!\n * mySchema.schema.users.findWhere({ id: 1 });  // Error: schema is undefined at runtime\n * ```\n */\nexport function defineSchema<\n  TCellMetadata = unknown,\n  TCurrentSchema extends Record<string, object> = Record<string, object>,\n  TCurrentDeclaration extends Record<string, TableSchemaDefinition | CellSchemaDefinition> = Record<\n    string,\n    TableSchemaDefinition | CellSchemaDefinition\n  >\n>(): CreateSchema<TCellMetadata, TCurrentSchema, TCurrentDeclaration> {\n  const declaration: Record<string, TableSchemaDefinition | CellSchemaDefinition> = {};\n\n  const builder: CreateSchema<TCellMetadata, TCurrentSchema, TCurrentDeclaration> = {\n    addTableSchema(namespace, address, headers) {\n      declaration[namespace] = {\n        type: \"table\",\n        tableName: address.tableName,\n        workbookName: address.workbookName,\n        headers: headers as any,\n      };\n      return builder as any;\n    },\n\n    addCellSchema(namespace, cellAddress, parse) {\n      declaration[namespace] = {\n        type: \"cell\",\n        cellAddress,\n        parse: parse as any,\n      };\n      return builder as any;\n    },\n\n    // schema is undefined at runtime - it only exists for TypeScript type inference\n    // The actual working schema is built by the FormulaEngine constructor\n    schema: undefined as any as TCurrentSchema,\n\n    declaration: declaration as TCurrentDeclaration,\n  };\n\n  return builder;\n}\n\ntype ParseFunction<TCellMetadata> = (\n  value: unknown,\n  metadata: TCellMetadata\n) => unknown;\n\nexport interface TableSchemaDefinition {\n  type: \"table\";\n  headers: Headers<unknown>;\n  tableName: string;\n  workbookName: string;\n}\n\nexport interface CellSchemaDefinition {\n  type: \"cell\";\n  cellAddress: CellAddress;\n  parse: (value: unknown, metadata: unknown) => unknown;\n}\n\ntype Headers<TCellMetadata> = Record<\n  string,\n  {\n    parse: ParseFunction<TCellMetadata>;\n    index: number;\n  }\n>;\n\n/**\n * Type representing the TableOrm methods exposed on the schema\n */\nexport type TableOrmSchema<TItem extends Record<string, unknown>> = {\n  findWhere(filter: Partial<TItem>): TItem | undefined;\n  findAllWhere(filter: Partial<TItem>): TItem[];\n  append(item: TItem): TItem;\n  updateWhere(filter: Partial<TItem>, update: Partial<TItem>): number;\n  removeWhere(filter: Partial<TItem>): number;\n  count(): number;\n};\n\n/**\n * Type representing the CellOrm methods exposed on the schema\n */\nexport type CellOrmSchema<TValue> = {\n  read(): TValue;\n  write(value: TValue): void;\n  getAddress(): CellAddress;\n};\n\nexport type SchemaDeclaration = Record<string, TableSchemaDefinition | CellSchemaDefinition>;\nexport type Schema = Record<string, object>;\n\nexport type CreateSchema<\n  TCellMetadata,\n  TCurrentSchema extends Schema,\n  TCurrentDeclaration extends SchemaDeclaration\n> = {\n  addTableSchema<T extends string, THeaders extends Headers<TCellMetadata>>(\n    namespace: T,\n    address: { workbookName: string; tableName: string },\n    headers: THeaders\n  ): CreateSchema<\n    TCellMetadata,\n    TCurrentSchema & {\n      [K in T]: TableOrmSchema<{\n        [H in keyof THeaders]: ReturnType<THeaders[H][\"parse\"]>;\n      }>;\n    },\n    TCurrentDeclaration & {\n      [K in T]: {\n        type: \"table\";\n        tableName: string;\n        workbookName: string;\n        headers: THeaders;\n      };\n    }\n  >;\n  addCellSchema<T extends string, TValue>(\n    namespace: T,\n    cellAddress: CellAddress,\n    parse: (value: unknown, metadata: TCellMetadata) => TValue\n  ): CreateSchema<\n    TCellMetadata,\n    TCurrentSchema & {\n      [K in T]: CellOrmSchema<TValue>;\n    },\n    TCurrentDeclaration & {\n      [K in T]: {\n        type: \"cell\";\n        cellAddress: CellAddress;\n        parse: (value: unknown, metadata: unknown) => unknown;\n      };\n    }\n  >;\n  schema: TCurrentSchema;\n  declaration: TCurrentDeclaration;\n};\n"
+  ],
+  "mappings": ";AAwBO,SAAS,YAOf,GAAqE;AAAA,EACpE,MAAM,cAA4E,CAAC;AAAA,EAEnF,MAAM,UAA4E;AAAA,IAChF,cAAc,CAAC,WAAW,SAAS,SAAS;AAAA,MAC1C,YAAY,aAAa;AAAA,QACvB,MAAM;AAAA,QACN,WAAW,QAAQ;AAAA,QACnB,cAAc,QAAQ;AAAA,QACtB;AAAA,MACF;AAAA,MACA,OAAO;AAAA;AAAA,IAGT,aAAa,CAAC,WAAW,aAAa,OAAO;AAAA,MAC3C,YAAY,aAAa;AAAA,QACvB,MAAM;AAAA,QACN;AAAA,QACA;AAAA,MACF;AAAA,MACA,OAAO;AAAA;AAAA,IAKT,QAAQ;AAAA,IAER;AAAA,EACF;AAAA,EAEA,OAAO;AAAA;",
+  "debugId": "DD0716E0FB48113C64756E2164756E21",
+  "names": []
+}

package/dist/mjs/core/{api → schema}/table-orm.mjs

@@ -1,4 +1,4 @@
-// src/core/api/table-orm.ts
+// src/core/schema/table-orm.ts
 import {
   rowToObject,
   objectToRowValues,
@@ -6,7 +6,7 @@ import {
   getTableRowCount,
   getNextEmptyRow,
   iterateTableRows
-} from "./api-helpers.mjs";
+} from "./schema-helpers.mjs";
 
 class TableOrm {
   engine;
@@ -145,4 +145,4 @@ export {
   TableOrm
 };
 
-//# debugId=745B273574CD6E8C64756E2164756E21
+//# debugId=266367D4DE8082EA64756E2164756E21

package/dist/mjs/core/schema/table-orm.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/core/schema/table-orm.ts"],
+  "sourcesContent": [
+    "/**\n * TableOrm - Object-Relational Mapping for table data\n *\n * Provides CRUD operations for table data with type-safe access.\n * Used as the `this` context for custom table API methods.\n */\n\nimport type { CellAddress, SerializedCellValue, TableDefinition } from \"../types.mjs\";\nimport type { FormulaEngine } from \"../engine.mjs\";\nimport {\n  rowToObject,\n  objectToRowValues,\n  matchesFilter,\n  getTableRowCount,\n  getNextEmptyRow,\n  iterateTableRows,\n  type TableSchemaHeaders,\n} from \"./schema-helpers.mjs\";\n\nexport class TableOrm<TItem extends Record<string, unknown>> {\n  constructor(\n    private engine: FormulaEngine<any, any>,\n    private workbookName: string,\n    private tableName: string,\n    private headers: TableSchemaHeaders,\n    private namespace: string\n  ) {}\n\n  /**\n   * Get the table definition from the engine\n   */\n  private getTable(): TableDefinition {\n    const table = this.engine._tableManager.getTable({\n      workbookName: this.workbookName,\n      name: this.tableName,\n    });\n\n    if (!table) {\n      throw new Error(\n        `Table \"${this.tableName}\" not found in workbook \"${this.workbookName}\"`\n      );\n    }\n\n    return table;\n  }\n\n  /**\n   * Find the first row matching the filter\n   */\n  findWhere(filter: Partial<TItem>): TItem | undefined {\n    const table = this.getTable();\n\n    for (const { rowIndex, isEmpty } of iterateTableRows(this.engine, table)) {\n      if (isEmpty) continue;\n\n      try {\n        const item = rowToObject<TItem>(\n          this.engine,\n          table,\n          rowIndex,\n          this.headers,\n          (cell) => this.engine.getCellMetadata(cell)\n        );\n\n        if (matchesFilter(item, filter)) {\n          return item;\n        }\n      } catch {\n        // Skip rows that fail parsing\n        continue;\n      }\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Find all rows matching the filter\n   */\n  findAllWhere(filter: Partial<TItem>): TItem[] {\n    const table = this.getTable();\n    const results: TItem[] = [];\n\n    for (const { rowIndex, isEmpty } of iterateTableRows(this.engine, table)) {\n      if (isEmpty) continue;\n\n      try {\n        const item = rowToObject<TItem>(\n          this.engine,\n          table,\n          rowIndex,\n          this.headers,\n          (cell) => this.engine.getCellMetadata(cell)\n        );\n\n        if (matchesFilter(item, filter)) {\n          results.push(item);\n        }\n      } catch {\n        // Skip rows that fail parsing\n        continue;\n      }\n    }\n\n    return results;\n  }\n\n  /**\n   * Append a new row to the table\n   */\n  append(item: TItem): TItem {\n    const table = this.getTable();\n    const nextRow = getNextEmptyRow(this.engine, table);\n    const values = objectToRowValues(item, this.headers);\n\n    // Write each cell value\n    for (const [colOffset, value] of values) {\n      const cellAddress: CellAddress = {\n        workbookName: table.workbookName,\n        sheetName: table.sheetName,\n        colIndex: table.start.colIndex + colOffset,\n        rowIndex: nextRow,\n      };\n\n      this.engine.setCellContent(cellAddress, value);\n    }\n\n    return item;\n  }\n\n  /**\n   * Update all rows matching the filter\n   * Returns the number of rows updated\n   */\n  updateWhere(filter: Partial<TItem>, update: Partial<TItem>): number {\n    const table = this.getTable();\n    let updatedCount = 0;\n\n    for (const { rowIndex, isEmpty } of iterateTableRows(this.engine, table)) {\n      if (isEmpty) continue;\n\n      try {\n        const item = rowToObject<TItem>(\n          this.engine,\n          table,\n          rowIndex,\n          this.headers,\n          (cell) => this.engine.getCellMetadata(cell)\n        );\n\n        if (matchesFilter(item, filter)) {\n          // Apply updates\n          const values = objectToRowValues(update as TItem, this.headers);\n\n          for (const [colOffset, value] of values) {\n            const cellAddress: CellAddress = {\n              workbookName: table.workbookName,\n              sheetName: table.sheetName,\n              colIndex: table.start.colIndex + colOffset,\n              rowIndex,\n            };\n\n            this.engine.setCellContent(cellAddress, value);\n          }\n\n          updatedCount++;\n        }\n      } catch {\n        // Skip rows that fail parsing\n        continue;\n      }\n    }\n\n    return updatedCount;\n  }\n\n  /**\n   * Remove all rows matching the filter\n   * Returns the number of rows removed\n   */\n  removeWhere(filter: Partial<TItem>): number {\n    const table = this.getTable();\n    let removedCount = 0;\n\n    // Collect rows to remove (in reverse order to avoid index shifting issues)\n    const rowsToRemove: number[] = [];\n\n    for (const { rowIndex, isEmpty } of iterateTableRows(this.engine, table)) {\n      if (isEmpty) continue;\n\n      try {\n        const item = rowToObject<TItem>(\n          this.engine,\n          table,\n          rowIndex,\n          this.headers,\n          (cell) => this.engine.getCellMetadata(cell)\n        );\n\n        if (matchesFilter(item, filter)) {\n          rowsToRemove.push(rowIndex);\n        }\n      } catch {\n        // Skip rows that fail parsing\n        continue;\n      }\n    }\n\n    // Remove rows in reverse order\n    for (const rowIndex of rowsToRemove.reverse()) {\n      // Clear all cells in the row\n      for (const header of Object.values(this.headers)) {\n        const cellAddress: CellAddress = {\n          workbookName: table.workbookName,\n          sheetName: table.sheetName,\n          colIndex: table.start.colIndex + header.index,\n          rowIndex,\n        };\n\n        this.engine.setCellContent(cellAddress, undefined);\n      }\n\n      removedCount++;\n    }\n\n    return removedCount;\n  }\n\n  /**\n   * Get the count of data rows in the table\n   */\n  count(): number {\n    const table = this.getTable();\n    return getTableRowCount(this.engine, table);\n  }\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "266367D4DE8082EA64756E2164756E21",
+  "names": []
+}

package/dist/mjs/lib.mjs

@@ -4,14 +4,13 @@ import { FormulaEngine } from "./core/engine.mjs";
 export * from "./core/types.mjs";
 export * from "./core/utils.mjs";
 export * from "./core/utils/color-utils.mjs";
-import { defineApi, createApi } from "./core/api/api.mjs";
-import { TableOrm } from "./core/api/table-orm.mjs";
-import { CellOrm } from "./core/api/cell-orm.mjs";
-import { SchemaValidationError } from "./core/managers/api-schema-manager.mjs";
+import { defineSchema } from "./core/schema/schema.mjs";
+import { TableOrm } from "./core/schema/table-orm.mjs";
+import { CellOrm } from "./core/schema/cell-orm.mjs";
+import { SchemaValidationError } from "./core/managers/schema-manager.mjs";
 import { SchemaIntegrityError } from "./core/commands/command-executor.mjs";
 export {
-  defineApi,
-  createApi,
+  defineSchema,
   TableOrm,
   SchemaValidationError,
   SchemaIntegrityError,
@@ -19,4 +18,4 @@ export {
   CellOrm
 };
 
-//# debugId=0A3DD3BE22C9A95664756E2164756E21
+//# debugId=14E82C883ABC721064756E2164756E21

package/dist/mjs/lib.mjs.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../../src/lib.ts"],
   "sourcesContent": [
-    "export { FormulaEngine } from \"./core/engine.mjs\";\nexport * from \"./core/types.mjs\";\nexport * from \"./core/utils.mjs\";\nexport * from \"./core/utils/color-utils.mjs\";\n\n// API Schema exports\nexport { defineApi, createApi } from \"./core/api/api.mjs\";\nexport type { CreateApi, Declaration, Api, TableApi, CellApi } from \"./core/api/api.mjs\";\nexport { TableOrm } from \"./core/api/table-orm.mjs\";\nexport { CellOrm } from \"./core/api/cell-orm.mjs\";\nexport { SchemaValidationError } from \"./core/managers/api-schema-manager.mjs\";\nexport type { ValidationResult } from \"./core/managers/api-schema-manager.mjs\";\n\n// Command Pattern exports\nexport { SchemaIntegrityError } from \"./core/commands/command-executor.mjs\";\nexport type { EngineAction, EngineCommand } from \"./core/commands/types.mjs\";\n"
+    "export { FormulaEngine } from \"./core/engine.mjs\";\nexport * from \"./core/types.mjs\";\nexport * from \"./core/utils.mjs\";\nexport * from \"./core/utils/color-utils.mjs\";\n\n// Schema exports\nexport { defineSchema } from \"./core/schema/schema.mjs\";\nexport type { CreateSchema, SchemaDeclaration, Schema, TableSchemaDefinition, CellSchemaDefinition, TableOrmSchema, CellOrmSchema } from \"./core/schema/schema.mjs\";\nexport { TableOrm } from \"./core/schema/table-orm.mjs\";\nexport { CellOrm } from \"./core/schema/cell-orm.mjs\";\nexport { SchemaValidationError } from \"./core/managers/schema-manager.mjs\";\nexport type { ValidationResult } from \"./core/managers/schema-manager.mjs\";\n\n// Command Pattern exports\nexport { SchemaIntegrityError } from \"./core/commands/command-executor.mjs\";\nexport type { EngineAction, EngineCommand } from \"./core/commands/types.mjs\";\n"
   ],
   "mappings": ";AAAA;AAAA;AACA;AACA;AACA;AAGA;AAEA;AACA;AACA;AAIA;",
-  "debugId": "0A3DD3BE22C9A95664756E2164756E21",
+  "debugId": "14E82C883ABC721064756E2164756E21",
   "names": []
 }

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/formula-engine",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "type": "module"
 }

package/dist/types/core/commands/command-executor.d.ts

@@ -8,7 +8,6 @@
  * - Undo/redo stacks
  * - Action serialization for persistence
  */
-import type { Declaration } from "../api/api";
 import type { EvaluationManager } from "../managers/evaluation-manager";
 import type { EventManager } from "../managers/event-manager";
 import type { EngineCommand, EngineAction, ExecuteOptions, SchemaValidationResult, SchemaValidationErrorInfo } from "./types";
@@ -24,14 +23,13 @@ export declare class SchemaIntegrityError extends Error {
  * CommandExecutor manages command execution with validation and undo/redo support.
  */
 export declare class CommandExecutor {
-    private apiDeclaration;
     private evaluationManager;
     private eventManager;
     private validateAllSchemas;
     private undoStack;
     private redoStack;
     private actionLog;
-    constructor(apiDeclaration: Declaration | undefined, evaluationManager: EvaluationManager, eventManager: EventManager, validateAllSchemas: () => SchemaValidationResult);
+    constructor(evaluationManager: EvaluationManager, eventManager: EventManager, validateAllSchemas: () => SchemaValidationResult);
     /**
      * Execute a command with optional schema validation.
      *

package/dist/types/core/commands/structure-commands.d.ts

@@ -3,7 +3,7 @@
  *
  * These commands all require re-evaluation after execution.
  */
-import type { ApiSchemaManager } from "../managers/api-schema-manager";
+import type { SchemaManager } from "../managers/schema-manager";
 import type { NamedExpressionManager } from "../managers/named-expression-manager";
 import type { ReferenceManager } from "../managers/reference-manager";
 import type { StyleManager } from "../managers/style-manager";
@@ -19,7 +19,7 @@ export interface StructureCommandDeps {
     tableManager: TableManager;
     styleManager: StyleManager;
     referenceManager: ReferenceManager;
-    apiSchemaManager: ApiSchemaManager;
+    apiSchemaManager: SchemaManager;
     renameSheetInFormula: (opts: {
         formula: string;
         oldSheetName: string;

package/dist/types/core/commands/table-commands.d.ts

@@ -6,7 +6,7 @@
 import type { TableManager } from "../managers/table-manager";
 import type { NamedExpressionManager } from "../managers/named-expression-manager";
 import type { WorkbookManager } from "../managers/workbook-manager";
-import type { ApiSchemaManager } from "../managers/api-schema-manager";
+import type { SchemaManager } from "../managers/schema-manager";
 import type { CellAddress, SerializedCellValue, SpreadsheetRangeEnd, TableDefinition } from "../types";
 import type { EngineCommand, EngineAction } from "./types";
 /**
@@ -16,7 +16,7 @@ export interface TableCommandDeps {
     tableManager: TableManager;
     namedExpressionManager: NamedExpressionManager;
     workbookManager: WorkbookManager;
-    apiSchemaManager: ApiSchemaManager;
+    apiSchemaManager: SchemaManager;
     getCellValue: (cellAddress: CellAddress) => SerializedCellValue;
     renameTableInFormula: (formula: string, oldName: string, newName: string) => string;
 }

package/dist/types/core/engine.d.ts

@@ -12,7 +12,10 @@ import { EventManager } from "./managers/event-manager";
 import { EvaluationManager } from "./managers/evaluation-manager";
 import { DependencyManager } from "./managers/dependency-manager";
 import { StyleManager } from "./managers/style-manager";
-import type { Api, CreateApi, Declaration } from "./api/api";
+import type { Schema, CreateSchema, SchemaDeclaration } from "./schema/schema";
+import { TableOrm } from "./schema/table-orm";
+import { CellOrm } from "./schema/cell-orm";
+import type { TableSchemaHeaders } from "./managers/schema-manager";
 import { type EngineAction } from "./commands/types";
 type Metadata = {
     cell?: unknown;
@@ -26,7 +29,7 @@ type MetadataType<TMetadata extends Metadata, TKey extends keyof Metadata> = TMe
  * @template TSheetMetadata - Consumer-defined type for sheet metadata (text boxes, frozen panes, etc.)
  * @template TWorkbookMetadata - Consumer-defined type for workbook metadata (themes, document properties, etc.)
  */
-export declare class FormulaEngine<TMetadata extends Metadata = Metadata, TCreateApi extends CreateApi<MetadataType<TMetadata, "cell">, Api, Declaration> | undefined = undefined> {
+export declare class FormulaEngine<TMetadata extends Metadata = Metadata, TCreateSchema extends CreateSchema<MetadataType<TMetadata, "cell">, Schema, SchemaDeclaration> | undefined = undefined> {
     private workbookManager;
     private namedExpressionManager;
     private tableManager;
@@ -37,10 +40,10 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata, TCreat
     private styleManager;
     private copyManager;
     private referenceManager;
-    private apiSchemaManager;
+    private schemaManager;
     private commandExecutor;
-    api: TCreateApi extends CreateApi<MetadataType<TMetadata, "cell">, Api, Declaration> ? TCreateApi["api"] : undefined;
-    private apiDeclaration;
+    schema: TCreateSchema extends CreateSchema<MetadataType<TMetadata, "cell">, Schema, SchemaDeclaration> ? TCreateSchema["schema"] : undefined;
+    private schemaDeclaration;
     /**
      * Public access to the store manager for testing
      */
@@ -52,14 +55,35 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata, TCreat
     _autoFillManager: AutoFill;
     _dependencyManager: DependencyManager;
     _styleManager: StyleManager;
-    constructor(api?: TCreateApi);
+    constructor(schema?: TCreateSchema);
     /**
      * Static factory method to build an empty engine
      * @template TC - Consumer-defined cell metadata type
      * @template TS - Consumer-defined sheet metadata type
      * @template TW - Consumer-defined workbook metadata type
      */
-    static buildEmpty<TMetadata extends Metadata = Metadata, TApiDeclaration extends CreateApi<MetadataType<TMetadata, "cell">, any, any> | undefined = undefined>(api?: TApiDeclaration): FormulaEngine<TMetadata, TApiDeclaration>;
+    static buildEmpty<TMetadata extends Metadata = Metadata, TSchemaDeclaration extends CreateSchema<MetadataType<TMetadata, "cell">, any, any> | undefined = undefined>(schema?: TSchemaDeclaration): FormulaEngine<TMetadata, TSchemaDeclaration>;
+    /**
+     * Add a table schema at runtime
+     * @param namespace - Unique namespace for the schema
+     * @param address - Table address (workbookName and tableName)
+     * @param headers - Table headers with parse functions
+     * @returns The TableOrm instance for immediate use
+     */
+    addTableSchema<THeaders extends TableSchemaHeaders<MetadataType<TMetadata, "cell">>>(namespace: string, address: {
+        workbookName: string;
+        tableName: string;
+    }, headers: THeaders): TableOrm<{
+        [K in keyof THeaders]: ReturnType<THeaders[K]["parse"]>;
+    }>;
+    /**
+     * Add a cell schema at runtime
+     * @param namespace - Unique namespace for the schema
+     * @param cellAddress - Address of the cell
+     * @param parse - Parse function for the cell value
+     * @returns The CellOrm instance for immediate use
+     */
+    addCellSchema<TValue>(namespace: string, cellAddress: CellAddress, parse: (value: unknown, metadata: MetadataType<TMetadata, "cell">) => TValue): CellOrm<TValue>;
     getCellEvaluationResult(cellAddress: CellAddress): SingleEvaluationResult | undefined;
     getCellValue(cellAddress: CellAddress, debug?: boolean): SerializedCellValue;
     /**

package/dist/types/core/managers/{api-schema-manager.d.ts → schema-manager.d.ts}

@@ -1,5 +1,5 @@
 /**
- * ApiSchemaManager - Manages API schema definitions and validation
+ * SchemaManager - Manages schema definitions and validation
  *
  * Tracks registered schemas and provides validation for cell writes,
  * spill operations, and copy/paste operations.
@@ -35,7 +35,7 @@ export declare class SchemaValidationError extends Error {
     originalError?: Error | undefined;
     constructor(message: string, cellAddress?: CellAddress | undefined, originalError?: Error | undefined);
 }
-export declare class ApiSchemaManager {
+export declare class SchemaManager {
     private tableManager;
     private schemas;
     constructor(tableManager: TableManager);
@@ -55,6 +55,10 @@ export declare class ApiSchemaManager {
      * Remove a schema
      */
     removeSchema(namespace: string): boolean;
+    /**
+     * Check if any schemas are registered
+     */
+    hasSchemas(): boolean;
     /**
      * Check if a cell is protected by a schema
      * Returns the schema info if protected, null otherwise

package/dist/types/core/schema/schema-builder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Schema Builder - Constructs the working schema from declarations
+ *
+ * This module is responsible for creating the actual working schema
+ * from the schema declarations when attached to a FormulaEngine.
+ */
+import type { FormulaEngine } from "../engine";
+import type { SchemaDeclaration, Schema } from "./schema";
+import type { SchemaManager } from "../managers/schema-manager";
+/**
+ * Build the working schema surface from declarations
+ *
+ * This creates TableOrm and CellOrm instances for each declared schema
+ * and returns them directly.
+ */
+export declare function buildSchemaFromDeclaration(engine: FormulaEngine<any, any>, declaration: SchemaDeclaration, schemaManager: SchemaManager): Schema;

package/dist/types/core/{api/api-helpers.d.ts → schema/schema-helpers.d.ts}

@@ -1,5 +1,5 @@
 /**
- * API Helper utilities for row/object conversion and filtering
+ * Schema Helper utilities for row/object conversion and filtering
  */
 import type { CellAddress, SerializedCellValue, TableDefinition } from "../types";
 import type { FormulaEngine } from "../engine";

package/dist/types/core/schema/schema.d.ts

@@ -0,0 +1,90 @@
+import type { CellAddress } from "../types";
+/**
+ * Define a schema for the FormulaEngine.
+ *
+ * The returned object contains:
+ * - `declaration`: The schema definitions for tables and cells
+ * - `schema`: A type-only placeholder (undefined at runtime) for TypeScript inference
+ *
+ * The actual working schema is only available through `engine.schema` after
+ * attaching the definition to a FormulaEngine instance.
+ *
+ * @example
+ * ```typescript
+ * const mySchema = defineSchema<CellMetadata>()
+ *   .addTableSchema("users", { workbookName: "wb1", tableName: "users" }, headers)
+ *   .addCellSchema("config", cellAddress, parse);
+ *
+ * const engine = new FormulaEngine(mySchema);
+ * engine.schema.users.findWhere({ id: 1 }); // Works!
+ * engine.schema.config.read(); // Works!
+ * mySchema.schema.users.findWhere({ id: 1 });  // Error: schema is undefined at runtime
+ * ```
+ */
+export declare function defineSchema<TCellMetadata = unknown, TCurrentSchema extends Record<string, object> = Record<string, object>, TCurrentDeclaration extends Record<string, TableSchemaDefinition | CellSchemaDefinition> = Record<string, TableSchemaDefinition | CellSchemaDefinition>>(): CreateSchema<TCellMetadata, TCurrentSchema, TCurrentDeclaration>;
+type ParseFunction<TCellMetadata> = (value: unknown, metadata: TCellMetadata) => unknown;
+export interface TableSchemaDefinition {
+    type: "table";
+    headers: Headers<unknown>;
+    tableName: string;
+    workbookName: string;
+}
+export interface CellSchemaDefinition {
+    type: "cell";
+    cellAddress: CellAddress;
+    parse: (value: unknown, metadata: unknown) => unknown;
+}
+type Headers<TCellMetadata> = Record<string, {
+    parse: ParseFunction<TCellMetadata>;
+    index: number;
+}>;
+/**
+ * Type representing the TableOrm methods exposed on the schema
+ */
+export type TableOrmSchema<TItem extends Record<string, unknown>> = {
+    findWhere(filter: Partial<TItem>): TItem | undefined;
+    findAllWhere(filter: Partial<TItem>): TItem[];
+    append(item: TItem): TItem;
+    updateWhere(filter: Partial<TItem>, update: Partial<TItem>): number;
+    removeWhere(filter: Partial<TItem>): number;
+    count(): number;
+};
+/**
+ * Type representing the CellOrm methods exposed on the schema
+ */
+export type CellOrmSchema<TValue> = {
+    read(): TValue;
+    write(value: TValue): void;
+    getAddress(): CellAddress;
+};
+export type SchemaDeclaration = Record<string, TableSchemaDefinition | CellSchemaDefinition>;
+export type Schema = Record<string, object>;
+export type CreateSchema<TCellMetadata, TCurrentSchema extends Schema, TCurrentDeclaration extends SchemaDeclaration> = {
+    addTableSchema<T extends string, THeaders extends Headers<TCellMetadata>>(namespace: T, address: {
+        workbookName: string;
+        tableName: string;
+    }, headers: THeaders): CreateSchema<TCellMetadata, TCurrentSchema & {
+        [K in T]: TableOrmSchema<{
+            [H in keyof THeaders]: ReturnType<THeaders[H]["parse"]>;
+        }>;
+    }, TCurrentDeclaration & {
+        [K in T]: {
+            type: "table";
+            tableName: string;
+            workbookName: string;
+            headers: THeaders;
+        };
+    }>;
+    addCellSchema<T extends string, TValue>(namespace: T, cellAddress: CellAddress, parse: (value: unknown, metadata: TCellMetadata) => TValue): CreateSchema<TCellMetadata, TCurrentSchema & {
+        [K in T]: CellOrmSchema<TValue>;
+    }, TCurrentDeclaration & {
+        [K in T]: {
+            type: "cell";
+            cellAddress: CellAddress;
+            parse: (value: unknown, metadata: unknown) => unknown;
+        };
+    }>;
+    schema: TCurrentSchema;
+    declaration: TCurrentDeclaration;
+};
+export {};

package/dist/types/core/{api → schema}/table-orm.d.ts

@@ -5,7 +5,7 @@
  * Used as the `this` context for custom table API methods.
  */
 import type { FormulaEngine } from "../engine";
-import { type TableSchemaHeaders } from "./api-helpers";
+import { type TableSchemaHeaders } from "./schema-helpers";
 export declare class TableOrm<TItem extends Record<string, unknown>> {
     private engine;
     private workbookName;

package/dist/types/lib.d.ts

@@ -2,11 +2,11 @@ export { FormulaEngine } from "./core/engine";
 export * from "./core/types";
 export * from "./core/utils";
 export * from "./core/utils/color-utils";
-export { defineApi, createApi } from "./core/api/api";
-export type { CreateApi, Declaration, Api, TableApi, CellApi } from "./core/api/api";
-export { TableOrm } from "./core/api/table-orm";
-export { CellOrm } from "./core/api/cell-orm";
-export { SchemaValidationError } from "./core/managers/api-schema-manager";
-export type { ValidationResult } from "./core/managers/api-schema-manager";
+export { defineSchema } from "./core/schema/schema";
+export type { CreateSchema, SchemaDeclaration, Schema, TableSchemaDefinition, CellSchemaDefinition, TableOrmSchema, CellOrmSchema } from "./core/schema/schema";
+export { TableOrm } from "./core/schema/table-orm";
+export { CellOrm } from "./core/schema/cell-orm";
+export { SchemaValidationError } from "./core/managers/schema-manager";
+export type { ValidationResult } from "./core/managers/schema-manager";
 export { SchemaIntegrityError } from "./core/commands/command-executor";
 export type { EngineAction, EngineCommand } from "./core/commands/types";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/formula-engine",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "module": "./dist/mjs/lib.mjs",
   "scripts": {
     "test": "bun test",