@ricsam/formula-engine 0.0.22 → 0.2.0

package/dist/types/core/schema/grid-orm.d.ts

@@ -0,0 +1,63 @@
+/**
+ * GridOrm - Object-Relational Mapping for grid/range data
+ *
+ * Provides read/write operations for a 2D range of cells with type-safe access.
+ * Supports both column-major and row-major array access patterns.
+ */
+import type { FiniteSpreadsheetRange, SerializedCellValue } from "../types";
+import type { FormulaEngine } from "../engine";
+export type GridParseFunction<TCellMetadata, TValue> = (value: unknown, metadata: TCellMetadata) => TValue;
+export type GridWriteFunction<TCellMetadata, TValue> = (value: TValue) => {
+    value: SerializedCellValue;
+    metadata?: TCellMetadata;
+};
+export declare class GridOrm<TValue, TCellMetadata = unknown> {
+    private engine;
+    private workbookName;
+    private sheetName;
+    private range;
+    private parser;
+    private writer;
+    private namespace;
+    private numCols;
+    private numRows;
+    constructor(engine: FormulaEngine<any, any>, workbookName: string, sheetName: string, range: FiniteSpreadsheetRange, parser: GridParseFunction<TCellMetadata, TValue>, writer: GridWriteFunction<TCellMetadata, TValue>, namespace: string);
+    /**
+     * Get the cell address for a given column and row index within the grid
+     */
+    private getCellAddress;
+    /**
+     * Read a single cell and parse it
+     */
+    private readCell;
+    /**
+     * Write a single cell using the write function
+     */
+    private writeCell;
+    /**
+     * Get all cells as a column-major 2D array (readonly)
+     * columns[colIndex][rowIndex]
+     */
+    get columns(): readonly (readonly TValue[])[];
+    /**
+     * Get all cells as a row-major 2D array (readonly)
+     * rows[rowIndex][colIndex]
+     */
+    get rows(): readonly (readonly TValue[])[];
+    /**
+     * Set a single value at the specified position
+     * Position is relative to the grid (0-indexed)
+     */
+    setValue(value: TValue, position: {
+        col: number;
+        row: number;
+    }): void;
+    /**
+     * Get a single value at the specified position
+     * Position is relative to the grid (0-indexed)
+     */
+    getValue(position: {
+        col: number;
+        row: number;
+    }): TValue;
+}

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

@@ -10,7 +10,7 @@ import type { SchemaManager } from "../managers/schema-manager";
 /**
  * Build the working schema surface from declarations
  *
- * This creates TableOrm and CellOrm instances for each declared schema
+ * This creates TableOrm, CellOrm, and GridOrm 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/schema/schema-helpers.d.ts

@@ -3,9 +3,14 @@
  */
 import type { CellAddress, SerializedCellValue, TableDefinition } from "../types";
 import type { FormulaEngine } from "../engine";
-export type ParseFunction<TCellMetadata = unknown> = (value: unknown, metadata: TCellMetadata) => unknown;
+export type ParseFunction<TCellMetadata = unknown> = (value: SerializedCellValue, metadata: TCellMetadata) => unknown;
+export type WriteFunction<TCellMetadata = unknown> = (value: unknown) => {
+    value: SerializedCellValue;
+    metadata?: TCellMetadata;
+};
 export type TableSchemaHeaders<TCellMetadata = unknown> = Record<string, {
     parse: ParseFunction<TCellMetadata>;
+    write: WriteFunction<TCellMetadata>;
     index: number;
 }>;
 /**
@@ -13,9 +18,16 @@ export type TableSchemaHeaders<TCellMetadata = unknown> = Record<string, {
  */
 export declare function rowToObject<TItem extends Record<string, unknown>>(engine: FormulaEngine<any, any>, table: TableDefinition, rowIndex: number, headers: TableSchemaHeaders, getCellMetadata?: (cell: CellAddress) => unknown): TItem;
 /**
- * Convert a typed object to cell values based on headers
+ * Result from objectToRowValues including both values and optional metadata
  */
-export declare function objectToRowValues<TItem extends Record<string, unknown>>(obj: TItem, headers: TableSchemaHeaders): Map<number, SerializedCellValue>;
+export type RowValuesResult<TCellMetadata = unknown> = {
+    values: Map<number, SerializedCellValue>;
+    metadata: Map<number, TCellMetadata>;
+};
+/**
+ * Convert a typed object to cell values based on headers using write functions
+ */
+export declare function objectToRowValues<TItem extends Record<string, unknown>, TCellMetadata = unknown>(obj: TItem, headers: TableSchemaHeaders<TCellMetadata>): RowValuesResult<TCellMetadata>;
 /**
  * Check if an object matches a filter predicate
  */

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

@@ -1,4 +1,4 @@
-import type { CellAddress } from "../types";
+import type { CellAddress, FiniteSpreadsheetRange, SerializedCellValue } from "../types";
 /**
  * Define a schema for the FormulaEngine.
  *
@@ -21,8 +21,7 @@ import type { CellAddress } from "../types";
  * 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 declare function defineSchema<TCellMetadata = unknown, TCurrentSchema extends Record<string, object> = Record<string, object>, TCurrentDeclaration extends Record<string, TableSchemaDefinition | CellSchemaDefinition | GridSchemaDefinition> = Record<string, TableSchemaDefinition | CellSchemaDefinition | GridSchemaDefinition>>(): CreateSchema<TCellMetadata, TCurrentSchema, TCurrentDeclaration>;
 export interface TableSchemaDefinition {
     type: "table";
     headers: Headers<unknown>;
@@ -33,9 +32,28 @@ export interface CellSchemaDefinition {
     type: "cell";
     cellAddress: CellAddress;
     parse: (value: unknown, metadata: unknown) => unknown;
+    write: (value: unknown) => {
+        value: SerializedCellValue;
+        metadata?: unknown;
+    };
+}
+export interface GridSchemaDefinition {
+    type: "grid";
+    workbookName: string;
+    sheetName: string;
+    range: FiniteSpreadsheetRange;
+    parse: (value: unknown, metadata: unknown) => unknown;
+    write: (value: unknown) => {
+        value: SerializedCellValue;
+        metadata?: unknown;
+    };
 }
 type Headers<TCellMetadata> = Record<string, {
-    parse: ParseFunction<TCellMetadata>;
+    parse: (value: SerializedCellValue, metadata: TCellMetadata) => unknown;
+    write: (value: any) => {
+        value: SerializedCellValue;
+        metadata?: TCellMetadata;
+    };
     index: number;
 }>;
 /**
@@ -57,8 +75,53 @@ export type CellOrmSchema<TValue> = {
     write(value: TValue): void;
     getAddress(): CellAddress;
 };
-export type SchemaDeclaration = Record<string, TableSchemaDefinition | CellSchemaDefinition>;
+/**
+ * Type representing the GridOrm methods exposed on the schema
+ */
+export type GridOrmSchema<TValue> = {
+    columns: readonly TValue[][];
+    rows: readonly TValue[][];
+    setValue(value: TValue, position: {
+        col: number;
+        row: number;
+    }): void;
+    getValue(position: {
+        col: number;
+        row: number;
+    }): TValue;
+};
+export type SchemaDeclaration = Record<string, TableSchemaDefinition | CellSchemaDefinition | GridSchemaDefinition>;
 export type Schema = Record<string, object>;
+/**
+ * Write function type for converting parsed values back to serializable form
+ */
+type WriteFunction<TValue, TCellMetadata> = (value: TValue) => {
+    value: SerializedCellValue;
+    metadata?: TCellMetadata;
+};
+/**
+ * Helper type to create the return type for addCellSchema/addGridSchema
+ */
+type AddCellSchemaResult<TCellMetadata, TCurrentSchema extends Schema, TCurrentDeclaration extends SchemaDeclaration, T extends string, TValue> = CreateSchema<TCellMetadata, TCurrentSchema & {
+    [K in T]: CellOrmSchema<TValue>;
+}, TCurrentDeclaration & {
+    [K in T]: {
+        type: "cell";
+        cellAddress: CellAddress;
+        parse: (value: unknown, metadata: unknown) => unknown;
+    };
+}>;
+type AddGridSchemaResult<TCellMetadata, TCurrentSchema extends Schema, TCurrentDeclaration extends SchemaDeclaration, T extends string, TValue> = CreateSchema<TCellMetadata, TCurrentSchema & {
+    [K in T]: GridOrmSchema<TValue>;
+}, TCurrentDeclaration & {
+    [K in T]: {
+        type: "grid";
+        workbookName: string;
+        sheetName: string;
+        range: FiniteSpreadsheetRange;
+        parse: (value: unknown, metadata: unknown) => unknown;
+    };
+}>;
 export type CreateSchema<TCellMetadata, TCurrentSchema extends Schema, TCurrentDeclaration extends SchemaDeclaration> = {
     addTableSchema<T extends string, THeaders extends Headers<TCellMetadata>>(namespace: T, address: {
         workbookName: string;
@@ -75,16 +138,30 @@ export type CreateSchema<TCellMetadata, TCurrentSchema extends Schema, TCurrentD
             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;
-        };
-    }>;
+    addCellSchema<T extends string, TValue>(namespace: T, cellAddress: CellAddress, parse: (value: unknown, metadata: TCellMetadata) => TValue, write: WriteFunction<TValue, TCellMetadata>): AddCellSchemaResult<TCellMetadata, TCurrentSchema, TCurrentDeclaration, T, TValue>;
+    addCellSchema<T extends string, TValue extends SerializedCellValue>(namespace: T, cellAddress: CellAddress, parse: (value: unknown, metadata: TCellMetadata) => TValue, write?: WriteFunction<TValue, TCellMetadata>): AddCellSchemaResult<TCellMetadata, TCurrentSchema, TCurrentDeclaration, T, TValue>;
+    addGridSchema<T extends string, TValue>(namespace: T, address: {
+        workbookName: string;
+        sheetName: string;
+    }, range: FiniteSpreadsheetRange, parse: (value: unknown, metadata: TCellMetadata) => TValue, write: WriteFunction<TValue, TCellMetadata>): AddGridSchemaResult<TCellMetadata, TCurrentSchema, TCurrentDeclaration, T, TValue>;
+    addGridSchema<T extends string, TValue extends SerializedCellValue>(namespace: T, address: {
+        workbookName: string;
+        sheetName: string;
+    }, range: FiniteSpreadsheetRange, parse: (value: unknown, metadata: TCellMetadata) => TValue, write?: WriteFunction<TValue, TCellMetadata>): AddGridSchemaResult<TCellMetadata, TCurrentSchema, TCurrentDeclaration, T, TValue>;
     schema: TCurrentSchema;
     declaration: TCurrentDeclaration;
 };
+export declare const defineHeader: <TValue, TMetadata>(index: number, parse: (value: SerializedCellValue, metadata: TMetadata) => TValue, write?: (value: TValue) => {
+    value: SerializedCellValue;
+    metadata?: TMetadata;
+}) => {
+    parse: (value: SerializedCellValue, metadata: TMetadata) => TValue;
+    write: ((value: TValue) => {
+        value: SerializedCellValue;
+        metadata?: TMetadata;
+    }) | ((value: TValue) => {
+        value: TValue;
+    });
+    index: number;
+};
 export {};

package/dist/types/lib.d.ts

@@ -2,7 +2,7 @@ export { FormulaEngine } from "./core/engine";
 export * from "./core/types";
 export * from "./core/utils";
 export * from "./core/utils/color-utils";
-export { defineSchema } from "./core/schema/schema";
+export { defineSchema, defineHeader } 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";

package/package.json

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