@b2bc-devkit/sheetorm 1.2.3 → 1.2.4

package/dist/npm/SheetOrm.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module SheetOrm
+ *
+ * NPM package entry point for the SheetORM library.
+ *
+ * Re-exports the core public API surface as static members of a single
+ * namespace class.  Consumer code imports from this module:
+ *
+ * ```ts
+ * import { SheetOrm } from "sheetorm";
+ * const { Record, Query, Decorators, IndexStore, Registry } = SheetOrm;
+ * ```
+ *
+ * This file is referenced by `tsconfig.npm.json` and the npm build
+ * script; it does **not** include GAS-specific helpers (e.g. demos,
+ * test runners) that live in `index.ts`.
+ */
+import { Decorators } from "./core/Decorators.js";
+import { Record } from "./core/Record.js";
+import { Registry } from "./core/Registry.js";
+import { IndexStore } from "./index/IndexStore.js";
+import { Query } from "./query/Query.js";
+/**
+ * Top-level namespace class that bundles every public SheetORM artifact.
+ *
+ * Designed as a single default import so consumers can destructure
+ * only the parts they need without deep import paths.
+ */
+export declare class SheetOrm {
+    /** ActiveRecord base class — extend this to define entity models. */
+    static readonly Record: typeof Record;
+    /** Fluent query builder for filtering, sorting, and paginating records. */
+    static readonly Query: typeof Query;
+    /** Property decorators: `@Field`, `@Indexed`, `@Required`. */
+    static readonly Decorators: typeof Decorators;
+    /** Secondary-index manager with n-gram text search. */
+    static readonly IndexStore: typeof IndexStore;
+    /** Singleton registry that tracks all registered entity classes. */
+    static readonly Registry: typeof Registry;
+}
+//# sourceMappingURL=SheetOrm.d.ts.map

package/dist/npm/SheetOrm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SheetOrm.d.ts","sourceRoot":"","sources":["../../src/SheetOrm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB,qEAAqE;IACrE,MAAM,CAAC,QAAQ,CAAC,MAAM,gBAAU;IAChC,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,CAAC,KAAK,eAAS;IAC9B,8DAA8D;IAC9D,MAAM,CAAC,QAAQ,CAAC,UAAU,oBAAc;IACxC,uDAAuD;IACvD,MAAM,CAAC,QAAQ,CAAC,UAAU,oBAAc;IACxC,oEAAoE;IACpE,MAAM,CAAC,QAAQ,CAAC,QAAQ,kBAAY;CACrC"}

package/dist/npm/SheetOrm.js

@@ -0,0 +1,41 @@
+/**
+ * @module SheetOrm
+ *
+ * NPM package entry point for the SheetORM library.
+ *
+ * Re-exports the core public API surface as static members of a single
+ * namespace class.  Consumer code imports from this module:
+ *
+ * ```ts
+ * import { SheetOrm } from "sheetorm";
+ * const { Record, Query, Decorators, IndexStore, Registry } = SheetOrm;
+ * ```
+ *
+ * This file is referenced by `tsconfig.npm.json` and the npm build
+ * script; it does **not** include GAS-specific helpers (e.g. demos,
+ * test runners) that live in `index.ts`.
+ */
+import { Decorators } from "./core/Decorators.js";
+import { Record } from "./core/Record.js";
+import { Registry } from "./core/Registry.js";
+import { IndexStore } from "./index/IndexStore.js";
+import { Query } from "./query/Query.js";
+/**
+ * Top-level namespace class that bundles every public SheetORM artifact.
+ *
+ * Designed as a single default import so consumers can destructure
+ * only the parts they need without deep import paths.
+ */
+export class SheetOrm {
+}
+/** ActiveRecord base class — extend this to define entity models. */
+SheetOrm.Record = Record;
+/** Fluent query builder for filtering, sorting, and paginating records. */
+SheetOrm.Query = Query;
+/** Property decorators: `@Field`, `@Indexed`, `@Required`. */
+SheetOrm.Decorators = Decorators;
+/** Secondary-index manager with n-gram text search. */
+SheetOrm.IndexStore = IndexStore;
+/** Singleton registry that tracks all registered entity classes. */
+SheetOrm.Registry = Registry;
+//# sourceMappingURL=SheetOrm.js.map

package/dist/npm/SheetOrm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SheetOrm.js","sourceRoot":"","sources":["../../src/SheetOrm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;;AACnB,qEAAqE;AACrD,eAAM,GAAG,MAAM,CAAC;AAChC,2EAA2E;AAC3D,cAAK,GAAG,KAAK,CAAC;AAC9B,8DAA8D;AAC9C,mBAAU,GAAG,UAAU,CAAC;AACxC,uDAAuD;AACvC,mBAAU,GAAG,UAAU,CAAC;AACxC,oEAAoE;AACpD,iBAAQ,GAAG,QAAQ,CAAC"}

package/dist/npm/core/Decorators.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Decorator-based metadata system for declaring Record model fields and indexes.
+ *
+ * Provides three property decorators:
+ *   - `@Indexed()` — mark a field for secondary indexing (lookups via IndexStore).
+ *   - `@Required()` — shorthand for `@Field({ required: true })`.
+ *   - `@Field()`   — override field metadata (type, required, defaultValue, etc.).
+ *
+ * And two discovery helpers:
+ *   - `getFields(ctor)`  — return all FieldDefinition[] for a class.
+ *   - `getIndexes(ctor)` — return all IndexDefinition[] for a class.
+ *
+ * Metadata is stored in module-scoped Maps keyed by constructor:
+ *   - `indexedMeta`  — primary @Indexed entries.
+ *   - `fieldMeta`    — primary @Field / @Required / @Indexed field patches.
+ *   - `fieldsCache`  — derived FieldDefinition[] (invalidated on decoration).
+ *   - `indexesCache` — derived IndexDefinition[] (invalidated on decoration).
+ *
+ * @module Decorators
+ */
+import type { FieldDefinition } from "./types/FieldDefinition.js";
+import type { FieldType } from "./types/FieldType.js";
+import type { IndexDefinition } from "./types/IndexDefinition.js";
+/** Constructor shape accepted by the decorators (any class that produces an object). */
+interface DecoratedModelCtor {
+    new (): object;
+}
+/**
+ * Mark a field as indexed for faster lookups via IndexStore.
+ *
+ * When a Record subclass has fields decorated with `@Indexed()`, SheetORM
+ * creates a combined index sheet (e.g. `idx_Cars`) and maintains index entries
+ * during save/delete operations. The `search` filter operator leverages the
+ * index for n-gram full-text search.
+ *
+ * @param options.unique - Enforce unique values across all entities (default: false).
+ * @param options.type   - Storage type hint for the index ("string" | "number" | "date").
+ * @returns A standard TypeScript property decorator.
+ *
+ * @example
+ * class Car extends Record {
+ *   @Indexed({ unique: true })
+ *   vin!: string;
+ *
+ *   @Indexed()
+ *   make!: string;
+ * }
+ */
+declare function Indexed(options?: {
+    unique?: boolean;
+    type?: "string" | "number" | "date";
+}): PropertyDecorator;
+/**
+ * Mark a field as required — shorthand for `@Field({ required: true })`.
+ *
+ * Required fields are validated during save(); an error is thrown if the
+ * value is null, undefined, or an empty string.
+ *
+ * @example
+ * class User extends Record {
+ *   @Required()
+ *   email!: string;
+ * }
+ */
+declare function Required(): PropertyDecorator;
+/**
+ * Override field metadata: storage type, required flag, default value, or
+ * reference table name.
+ *
+ * Fields that do not carry any decorator are still auto-discovered from a
+ * temporary instance's own properties. Use `@Field()` when you need to
+ * explicitly set the storage type or a default value.
+ *
+ * @param options.type           - Storage type ("string" | "number" | "boolean" | "date" | "json" | "reference").
+ * @param options.required       - Validate non-empty on save (default: false).
+ * @param options.defaultValue   - Fallback value when the field is undefined.
+ * @param options.referenceTable - Related table name (for "reference" type fields).
+ *
+ * @example
+ * class Product extends Record {
+ *   @Field({ type: "number", defaultValue: 0 })
+ *   price!: number;
+ *
+ *   @Field({ type: "json" })
+ *   metadata!: Record<string, unknown>;
+ * }
+ */
+declare function Field(options?: {
+    type?: FieldType;
+    required?: boolean;
+    defaultValue?: unknown;
+    referenceTable?: string;
+}): PropertyDecorator;
+/**
+ * Discover all user-defined fields for a Record subclass.
+ *
+ * Merges two sources:
+ *   1. **Own properties** from a temporary instance — captures ESNext [[Define]]
+ *      class fields that become own properties without a decorator.
+ *   2. **Decorator metadata** from `@Indexed` / `@Field` / `@Required` — captures
+ *      fields declared with [[Set]] semantics (TypeScript `useDefineForClassFields: false`).
+ *
+ * Results are cached per constructor and invalidated whenever a decorator fires.
+ *
+ * @param ctor - Model constructor to inspect.
+ * @returns Array of FieldDefinition objects (one per user-defined property).
+ */
+declare function getFields(ctor: DecoratedModelCtor): FieldDefinition[];
+/**
+ * Get all index definitions for a Record subclass (from `@Indexed` decorators).
+ *
+ * @param ctor - Model constructor to inspect.
+ * @returns Array of IndexDefinition objects.
+ */
+declare function getIndexes(ctor: DecoratedModelCtor): IndexDefinition[];
+/**
+ * Reset derived decorator caches (fieldsCache and indexesCache).
+ *
+ * Called by `Registry.reset()` during testing to ensure a clean state.
+ * Primary metadata (`fieldMeta` and `indexedMeta`) is set at class-definition
+ * time by decorators and must NOT be cleared here — only derived caches.
+ */
+declare function resetDecoratorCaches(): void;
+/**
+ * Public decorator utility class.
+ *
+ * Wraps the three property decorators and two discovery functions
+ * as static methods, following the SheetORM one-export-per-file pattern.
+ */
+export declare class Decorators {
+    /** Property decorator: mark a field for secondary indexing. */
+    static Indexed: typeof Indexed;
+    /** Property decorator: mark a field as required (shorthand). */
+    static Required: typeof Required;
+    /** Property decorator: set explicit field metadata. */
+    static Field: typeof Field;
+    /** Discover all field definitions for a model class. */
+    static getFields: typeof getFields;
+    /** Discover all index definitions for a model class. */
+    static getIndexes: typeof getIndexes;
+    /** Reset derived caches (for testing). */
+    static resetDecoratorCaches: typeof resetDecoratorCaches;
+}
+export {};
+//# sourceMappingURL=Decorators.d.ts.map

package/dist/npm/core/Decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decorators.d.ts","sourceRoot":"","sources":["../../../src/core/Decorators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,wFAAwF;AACxF,UAAU,kBAAkB;IAC1B,QAAQ,MAAM,CAAC;CAChB;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iBAAS,OAAO,CAAC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAA;CAAE,GAAG,iBAAiB,CAYvG;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,QAAQ,IAAI,iBAAiB,CAKrC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,KAAK,CAAC,OAAO,CAAC,EAAE;IACvB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,iBAAiB,CAKpB;AAID;;;;;;;;;;;;;GAaG;AACH,iBAAS,SAAS,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,EAAE,CAgC9D;AAED;;;;;GAKG;AACH,iBAAS,UAAU,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,EAAE,CAK/D;AAED;;;;;;GAMG;AACH,iBAAS,oBAAoB,IAAI,IAAI,CAGpC;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,+DAA+D;IAC/D,MAAM,CAAC,OAAO,iBAAW;IAEzB,gEAAgE;IAChE,MAAM,CAAC,QAAQ,kBAAY;IAE3B,uDAAuD;IACvD,MAAM,CAAC,KAAK,eAAS;IAErB,wDAAwD;IACxD,MAAM,CAAC,SAAS,mBAAa;IAE7B,wDAAwD;IACxD,MAAM,CAAC,UAAU,oBAAc;IAE/B,0CAA0C;IAC1C,MAAM,CAAC,oBAAoB,8BAAwB;CACpD"}

package/dist/npm/core/Decorators.js

@@ -0,0 +1,226 @@
+/**
+ * Decorator-based metadata system for declaring Record model fields and indexes.
+ *
+ * Provides three property decorators:
+ *   - `@Indexed()` — mark a field for secondary indexing (lookups via IndexStore).
+ *   - `@Required()` — shorthand for `@Field({ required: true })`.
+ *   - `@Field()`   — override field metadata (type, required, defaultValue, etc.).
+ *
+ * And two discovery helpers:
+ *   - `getFields(ctor)`  — return all FieldDefinition[] for a class.
+ *   - `getIndexes(ctor)` — return all IndexDefinition[] for a class.
+ *
+ * Metadata is stored in module-scoped Maps keyed by constructor:
+ *   - `indexedMeta`  — primary @Indexed entries.
+ *   - `fieldMeta`    — primary @Field / @Required / @Indexed field patches.
+ *   - `fieldsCache`  — derived FieldDefinition[] (invalidated on decoration).
+ *   - `indexesCache` — derived IndexDefinition[] (invalidated on decoration).
+ *
+ * @module Decorators
+ */
+// ─── Metadata storage ────────────────────────────────
+/** Primary storage for @Indexed() entries — one array of IndexDefinition per class. */
+const indexedMeta = new Map();
+/** Primary storage for per-field decorator patches — nested map: ctor → fieldName → partial def. */
+const fieldMeta = new Map();
+/** Derived cache: merged FieldDefinition[] per class (cleared when a decorator fires). */
+const fieldsCache = new Map();
+/** Derived cache: IndexDefinition[] per class (cleared when @Indexed fires). */
+const indexesCache = new Map();
+/**
+ * Merge a partial FieldDefinition patch into the metadata store for a given class/field.
+ *
+ * If the class or field has no metadata yet, creates fresh entries.
+ * Invalidates the fieldsCache so the next `getFields()` call rebuilds.
+ *
+ * @param ctor        - The model constructor (class).
+ * @param propertyKey - Decorated property name.
+ * @param patch       - Partial field definition to merge.
+ */
+function upsertFieldMetadata(ctor, propertyKey, patch) {
+    if (!fieldMeta.has(ctor))
+        fieldMeta.set(ctor, new Map());
+    const name = String(propertyKey);
+    const existing = fieldMeta.get(ctor).get(name) || {};
+    // Merge existing metadata with new patch; `name` is always set
+    fieldMeta.get(ctor).set(name, {
+        name,
+        ...existing,
+        ...patch,
+    });
+    // Invalidate derived cache
+    fieldsCache.delete(ctor);
+}
+// ─── Property Decorators ─────────────────────────────
+/**
+ * Mark a field as indexed for faster lookups via IndexStore.
+ *
+ * When a Record subclass has fields decorated with `@Indexed()`, SheetORM
+ * creates a combined index sheet (e.g. `idx_Cars`) and maintains index entries
+ * during save/delete operations. The `search` filter operator leverages the
+ * index for n-gram full-text search.
+ *
+ * @param options.unique - Enforce unique values across all entities (default: false).
+ * @param options.type   - Storage type hint for the index ("string" | "number" | "date").
+ * @returns A standard TypeScript property decorator.
+ *
+ * @example
+ * class Car extends Record {
+ *   @Indexed({ unique: true })
+ *   vin!: string;
+ *
+ *   @Indexed()
+ *   make!: string;
+ * }
+ */
+function Indexed(options) {
+    return (target, propertyKey) => {
+        const ctor = target.constructor;
+        // Register the index definition
+        if (!indexedMeta.has(ctor))
+            indexedMeta.set(ctor, []);
+        indexedMeta.get(ctor).push({ field: String(propertyKey), ...options });
+        // Also register in fieldMeta so the field appears in getFields() even
+        // when using ES2022 [[Set]] class field semantics (no own property on prototype)
+        upsertFieldMetadata(ctor, propertyKey, {});
+        // Invalidate index cache
+        indexesCache.delete(ctor);
+    };
+}
+/**
+ * Mark a field as required — shorthand for `@Field({ required: true })`.
+ *
+ * Required fields are validated during save(); an error is thrown if the
+ * value is null, undefined, or an empty string.
+ *
+ * @example
+ * class User extends Record {
+ *   @Required()
+ *   email!: string;
+ * }
+ */
+function Required() {
+    return (target, propertyKey) => {
+        const ctor = target.constructor;
+        upsertFieldMetadata(ctor, propertyKey, { required: true });
+    };
+}
+/**
+ * Override field metadata: storage type, required flag, default value, or
+ * reference table name.
+ *
+ * Fields that do not carry any decorator are still auto-discovered from a
+ * temporary instance's own properties. Use `@Field()` when you need to
+ * explicitly set the storage type or a default value.
+ *
+ * @param options.type           - Storage type ("string" | "number" | "boolean" | "date" | "json" | "reference").
+ * @param options.required       - Validate non-empty on save (default: false).
+ * @param options.defaultValue   - Fallback value when the field is undefined.
+ * @param options.referenceTable - Related table name (for "reference" type fields).
+ *
+ * @example
+ * class Product extends Record {
+ *   @Field({ type: "number", defaultValue: 0 })
+ *   price!: number;
+ *
+ *   @Field({ type: "json" })
+ *   metadata!: Record<string, unknown>;
+ * }
+ */
+function Field(options) {
+    return (target, propertyKey) => {
+        const ctor = target.constructor;
+        upsertFieldMetadata(ctor, propertyKey, options ?? {});
+    };
+}
+// ─── Field & Index Discovery ─────────────────────────
+/**
+ * Discover all user-defined fields for a Record subclass.
+ *
+ * Merges two sources:
+ *   1. **Own properties** from a temporary instance — captures ESNext [[Define]]
+ *      class fields that become own properties without a decorator.
+ *   2. **Decorator metadata** from `@Indexed` / `@Field` / `@Required` — captures
+ *      fields declared with [[Set]] semantics (TypeScript `useDefineForClassFields: false`).
+ *
+ * Results are cached per constructor and invalidated whenever a decorator fires.
+ *
+ * @param ctor - Model constructor to inspect.
+ * @returns Array of FieldDefinition objects (one per user-defined property).
+ */
+function getFields(ctor) {
+    // Return cached result if available
+    if (fieldsCache.has(ctor))
+        return fieldsCache.get(ctor);
+    // 1. Discover own properties from a temp instance (undecorated fields defined via [[Define]])
+    const temp = new ctor();
+    const discoveredNames = new Set(Object.getOwnPropertyNames(temp));
+    // 2. Add names registered through @Indexed decorator
+    const idxMeta = indexedMeta.get(ctor) || [];
+    for (const idx of idxMeta)
+        discoveredNames.add(idx.field);
+    // 3. Add names registered through @Field / @Required decorators
+    const fMeta = fieldMeta.get(ctor) || new Map();
+    for (const name of fMeta.keys())
+        discoveredNames.add(name);
+    // 4. Build the final FieldDefinition array, merging decorator overrides
+    const fields = [];
+    for (const name of discoveredNames) {
+        const override = fMeta.get(name);
+        fields.push({
+            name,
+            type: override?.type,
+            required: override?.required,
+            defaultValue: override?.defaultValue,
+            referenceTable: override?.referenceTable,
+        });
+    }
+    // Cache for subsequent calls
+    fieldsCache.set(ctor, fields);
+    return fields;
+}
+/**
+ * Get all index definitions for a Record subclass (from `@Indexed` decorators).
+ *
+ * @param ctor - Model constructor to inspect.
+ * @returns Array of IndexDefinition objects.
+ */
+function getIndexes(ctor) {
+    if (indexesCache.has(ctor))
+        return indexesCache.get(ctor);
+    const indexes = indexedMeta.get(ctor) || [];
+    indexesCache.set(ctor, indexes);
+    return indexes;
+}
+/**
+ * Reset derived decorator caches (fieldsCache and indexesCache).
+ *
+ * Called by `Registry.reset()` during testing to ensure a clean state.
+ * Primary metadata (`fieldMeta` and `indexedMeta`) is set at class-definition
+ * time by decorators and must NOT be cleared here — only derived caches.
+ */
+function resetDecoratorCaches() {
+    fieldsCache.clear();
+    indexesCache.clear();
+}
+/**
+ * Public decorator utility class.
+ *
+ * Wraps the three property decorators and two discovery functions
+ * as static methods, following the SheetORM one-export-per-file pattern.
+ */
+export class Decorators {
+}
+/** Property decorator: mark a field for secondary indexing. */
+Decorators.Indexed = Indexed;
+/** Property decorator: mark a field as required (shorthand). */
+Decorators.Required = Required;
+/** Property decorator: set explicit field metadata. */
+Decorators.Field = Field;
+/** Discover all field definitions for a model class. */
+Decorators.getFields = getFields;
+/** Discover all index definitions for a model class. */
+Decorators.getIndexes = getIndexes;
+/** Reset derived caches (for testing). */
+Decorators.resetDecoratorCaches = resetDecoratorCaches;
+//# sourceMappingURL=Decorators.js.map

package/dist/npm/core/Decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decorators.js","sourceRoot":"","sources":["../../../src/core/Decorators.ts"],"names":[],"mappings":"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"}

package/dist/npm/core/Record.d.ts

@@ -0,0 +1,184 @@
+/**
+ * ActiveRecord base class for ORM-managed models.
+ *
+ * Subclass `Record` to define entities stored in Google Sheets.  Fields
+ * are auto-discovered from ESNext class field declarations at registration
+ * time via the decorator metadata system ({@link Decorators}).
+ *
+ * Follows the **ActiveRecord** pattern — each instance knows how to
+ * `save()` and `delete()` itself, while static methods like `find()`,
+ * `where()`, and `query()` provide collection-level operations.
+ *
+ * @example
+ * ```ts
+ * class Car extends Record {
+ *   brand = "";
+ *   year  = 0;
+ * }
+ * const car = Car.create({ brand: "Toyota", year: 2024 }).save();
+ * ```
+ *
+ * @module Record
+ */
+import type { Entity } from "./types/Entity.js";
+import type { FilterOperator } from "./types/FilterOperator.js";
+import type { QueryOptions } from "./types/QueryOptions.js";
+import type { PaginatedResult } from "./types/PaginatedResult.js";
+import type { GroupResult } from "./types/GroupResult.js";
+import { Query } from "../query/Query.js";
+import type { RecordConstructor } from "./RecordConstructor.js";
+/**
+ * Base class for all SheetORM models.
+ *
+ * Provides both instance-level persistence (`save`, `delete`) and
+ * static query helpers (`find`, `where`, `query`, `select`, `groupBy`,
+ * `saveAll`).  System columns (`__id`, `__createdAt`, `__updatedAt`)
+ * are declared here so every subclass inherits them.
+ */
+export declare class Record implements Entity {
+    /** UUID primary key, assigned automatically on first save. */
+    __id: string;
+    /** ISO-8601 creation timestamp, set by SheetRepository on insert. */
+    __createdAt: string | undefined;
+    /** ISO-8601 last-update timestamp, set by SheetRepository on every save. */
+    __updatedAt: string | undefined;
+    /** Index signature allowing arbitrary field access by name. */
+    [key: string]: unknown;
+    /**
+     * Convention-based table name derived from the class name.
+     * e.g. class `Car` → `"tbl_Cars"`.
+     */
+    static get tableName(): string;
+    /**
+     * Convention-based combined index table name.
+     * e.g. class `Car` → `"idx_Cars"`.
+     */
+    static get indexTableName(): string;
+    /**
+     * Whether the auto-created sheet should be protected.
+     * Override in a subclass to return `true` and enable sheet protection.
+     */
+    static isProtected(): boolean;
+    /**
+     * Email addresses of editors allowed to edit the protected sheet.
+     * Only used when `isProtected()` returns `true`.
+     * Override in a subclass to specify allowed editors.
+     */
+    static protectedFor(): string[];
+    /**
+     * Whether the auto-created sheet should be hidden from the tab bar.
+     * Override in a subclass to return `true` and hide the sheet.
+     * Hidden sheets are still accessible from the "All sheets" menu.
+     */
+    static isHidden(): boolean;
+    /**
+     * Create an in-memory instance pre-populated with the given data.
+     * The instance is **not** persisted until `save()` is called.
+     *
+     * @param data - Plain object whose keys map to field names.
+     * @returns A new, unsaved Record subclass instance.
+     */
+    static create<T extends Record>(this: RecordConstructor<T>, data: {
+        [key: string]: unknown;
+    }): T;
+    /**
+     * Persist this instance to the underlying Google Sheet.
+     *
+     * On first save (no `__id`) a new row is inserted; on subsequent
+     * saves the existing row is updated in-place.  Only fields declared
+     * via decorators (or auto-discovered) are written; dynamic index-
+     * signature properties are ignored.
+     *
+     * @returns `this` for fluent chaining.
+     */
+    save(): this;
+    /**
+     * Delete this instance's row from the sheet.
+     * @returns `true` if the row was found and deleted, `false` if `__id` is missing.
+     */
+    delete(): boolean;
+    /**
+     * Fluent setter — updates a single field and returns `this`.
+     * @param field - The field name to set.
+     * @param value - The new value.
+     */
+    set(field: string, value: unknown): this;
+    /**
+     * Read a single field value by name.
+     * @param field - The field name to read.
+     */
+    get(field: string): unknown;
+    /**
+     * Serialise this Record to a plain object.
+     *
+     * Only includes declared class fields (from decorator metadata) plus
+     * system columns.  Dynamic properties set via the index signature are
+     * intentionally excluded to keep JSON output predictable.
+     */
+    toJSON(): {
+        [key: string]: unknown;
+    };
+    /**
+     * Start a fluent query chain with an initial filter.
+     * Equivalent to `Record.query().where(field, operator, value)`.
+     */
+    static where<T extends Record>(this: RecordConstructor<T>, field: string, operator: FilterOperator, value: unknown): Query<T>;
+    /**
+     * Look up a single record by its UUID primary key.
+     * Uses the repository's fast-path cache when available.
+     *
+     * @returns The hydrated instance, or `null` if not found.
+     */
+    static findById<T extends Record>(this: RecordConstructor<T>, id: string): T | null;
+    /**
+     * Return all records matching the optional query options.
+     * Without options, returns every record in the table.
+     */
+    static find<T extends Record>(this: RecordConstructor<T>, options?: QueryOptions): T[];
+    /**
+     * Return the first record matching the query options, or `null`.
+     */
+    static findOne<T extends Record>(this: RecordConstructor<T>, options?: QueryOptions): T | null;
+    /** Count records matching the optional query options. */
+    static count(options?: QueryOptions): number;
+    /**
+     * Delete all records matching the query options.
+     * @returns The number of records deleted.
+     */
+    static deleteAll(options?: QueryOptions): number;
+    /**
+     * Start an empty fluent query chain.
+     * Call `.where()`, `.orderBy()`, `.limit()`, etc. to build the query.
+     */
+    static query<T extends Record>(this: RecordConstructor<T>): Query<T>;
+    /**
+     * Return a paginated subset of records.
+     *
+     * @param offset  - Number of records to skip (0-based).
+     * @param limit   - Maximum number of records to return.
+     * @param options - Optional filters/sorting.
+     * @returns A {@link PaginatedResult} with `items`, `total`, `offset`, `limit`.
+     */
+    static select<T extends Record>(this: RecordConstructor<T>, offset: number, limit: number, options?: QueryOptions): PaginatedResult<T>;
+    /**
+     * Group records by a field value.
+     *
+     * @param field   - The field to group by.
+     * @param options - Optional pre-grouping filters.
+     * @returns An array of {@link GroupResult}, each with `key` and `items`.
+     */
+    static groupBy<T extends Record>(this: RecordConstructor<T>, field: string, options?: QueryOptions): GroupResult<T>[];
+    /**
+     * Batch-save multiple records in a single operation.
+     *
+     * Delegates to `SheetRepository.saveAll()` which uses entity-batch and
+     * index-batch optimisations to minimise GAS API calls.
+     *
+     * @param items - Array of plain data objects.
+     * @returns Array of hydrated, persisted Record instances.
+     */
+    static saveAll<T extends Record>(this: RecordConstructor<T>, items: Array<{
+        [key: string]: unknown;
+    }>): T[];
+}
+//# sourceMappingURL=Record.d.ts.map

package/dist/npm/core/Record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Record.d.ts","sourceRoot":"","sources":["../../../src/core/Record.ts"],"names":[],"mappings":"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"}