@b2bc-devkit/sheetorm 1.2.3 → 1.2.4

package/dist/npm/core/Record.js

@@ -0,0 +1,321 @@
+/**
+ * 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 { Registry } from "./Registry.js";
+import { Query } from "../query/Query.js";
+import { Decorators } from "./Decorators.js";
+/**
+ * Cast an unknown class reference to the internal {@link RecordStatic}
+ * shape so that `tableName`, `indexTableName`, etc. are available.
+ */
+function asCtor(cls) {
+    return cls;
+}
+/**
+ * Hydrate raw Entity objects into fully-typed Record instances.
+ *
+ * Allocates the result array up-front and uses `Object.assign` to copy
+ * entity properties onto each freshly-constructed instance.
+ *
+ * @param ctor     - The concrete Record subclass constructor.
+ * @param entities - Raw entity rows returned by SheetRepository.
+ * @returns An array of hydrated Record subclass instances.
+ */
+function toInstances(ctor, entities) {
+    const len = entities.length;
+    const result = new Array(len);
+    for (let i = 0; i < len; i++) {
+        const instance = new ctor();
+        Object.assign(instance, entities[i]);
+        result[i] = instance;
+    }
+    return result;
+}
+/**
+ * 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 class Record {
+    /**
+     * Convention-based table name derived from the class name.
+     * e.g. class `Car` → `"tbl_Cars"`.
+     */
+    static get tableName() {
+        return "tbl_" + this.name + "s";
+    }
+    /**
+     * Convention-based combined index table name.
+     * e.g. class `Car` → `"idx_Cars"`.
+     */
+    static get indexTableName() {
+        return "idx_" + this.name + "s";
+    }
+    /**
+     * Whether the auto-created sheet should be protected.
+     * Override in a subclass to return `true` and enable sheet protection.
+     */
+    static isProtected() {
+        return false;
+    }
+    /**
+     * 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() {
+        return [];
+    }
+    /**
+     * 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() {
+        return false;
+    }
+    // ─── Static Factory ──────────────────────────────
+    /**
+     * 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(data) {
+        const instance = new this();
+        return Object.assign(instance, data);
+    }
+    // ─── Instance Methods ────────────────────────────
+    /**
+     * 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() {
+        const Ctor = this.constructor;
+        const fields = Decorators.getFields(Ctor);
+        const repo = Registry.getInstance().ensureRepository(Ctor);
+        // Build a partial entity containing only declared fields with defined values
+        const partial = {};
+        for (let i = 0; i < fields.length; i++) {
+            const name = fields[i].name;
+            const val = this[name];
+            if (val !== undefined) {
+                partial[name] = val;
+            }
+        }
+        if (this.__id)
+            partial.__id = this.__id;
+        // Delegate to the repository and hydrate the returned entity (with system columns)
+        const saved = repo.save(partial);
+        Object.assign(this, saved);
+        return this;
+    }
+    /**
+     * Delete this instance's row from the sheet.
+     * @returns `true` if the row was found and deleted, `false` if `__id` is missing.
+     */
+    delete() {
+        if (!this.__id)
+            return false;
+        const Ctor = this.constructor;
+        const repo = Registry.getInstance().ensureRepository(Ctor);
+        return repo.delete(this.__id);
+    }
+    /**
+     * Fluent setter — updates a single field and returns `this`.
+     * @param field - The field name to set.
+     * @param value - The new value.
+     */
+    set(field, value) {
+        this[field] = value;
+        return this;
+    }
+    /**
+     * Read a single field value by name.
+     * @param field - The field name to read.
+     */
+    get(field) {
+        return this[field];
+    }
+    /**
+     * 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() {
+        const Ctor = this.constructor;
+        const fields = Decorators.getFields(Ctor);
+        const result = {
+            __id: this.__id,
+            __createdAt: this.__createdAt,
+            __updatedAt: this.__updatedAt,
+        };
+        for (let i = 0; i < fields.length; i++) {
+            const name = fields[i].name;
+            result[name] = this[name];
+        }
+        return result;
+    }
+    // ─── Static Query Methods ────────────────────────
+    /**
+     * Start a fluent query chain with an initial filter.
+     * Equivalent to `Record.query().where(field, operator, value)`.
+     */
+    static where(field, operator, value) {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        return new Query(() => toInstances(this, repo.find())).where(field, operator, value);
+    }
+    /**
+     * 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(id) {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        const entity = repo.findById(id);
+        if (!entity)
+            return null;
+        return Object.assign(new this(), entity);
+    }
+    /**
+     * Return all records matching the optional query options.
+     * Without options, returns every record in the table.
+     */
+    static find(options) {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        return toInstances(this, repo.find(options));
+    }
+    /**
+     * Return the first record matching the query options, or `null`.
+     */
+    static findOne(options) {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        const entity = repo.findOne(options);
+        if (!entity)
+            return null;
+        return Object.assign(new this(), entity);
+    }
+    /** Count records matching the optional query options. */
+    static count(options) {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        return repo.count(options);
+    }
+    /**
+     * Delete all records matching the query options.
+     * @returns The number of records deleted.
+     */
+    static deleteAll(options) {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        return repo.deleteAll(options);
+    }
+    /**
+     * Start an empty fluent query chain.
+     * Call `.where()`, `.orderBy()`, `.limit()`, etc. to build the query.
+     */
+    static query() {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        return new Query(() => toInstances(this, repo.find()));
+    }
+    /**
+     * 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(offset, limit, options) {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        const result = repo.select(offset, limit, options);
+        return {
+            ...result,
+            items: toInstances(this, result.items),
+        };
+    }
+    /**
+     * 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(field, options) {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        const groups = repo.groupBy(field, options);
+        return groups.map((g) => ({
+            ...g,
+            items: toInstances(this, g.items),
+        }));
+    }
+    /**
+     * 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(items) {
+        const repo = Registry.getInstance().ensureRepository(asCtor(this));
+        const entities = repo.saveAll(items);
+        return toInstances(this, entities);
+    }
+}
+// ─── Wire up Query.from() resolver ──────────
+// This glue code teaches Query.from(ClassName) how to locate the correct
+// Registry entry and build a data-loader function without creating a
+// circular dependency between Query and Record at import time.
+Query._setFromResolver((classOrName) => {
+    const registry = Registry.getInstance();
+    let ctor;
+    if (typeof classOrName === "string") {
+        // Look up by class name — the class must have been imported/registered first
+        const found = registry.getClassByName(classOrName);
+        if (!found) {
+            throw new Error(`Record class "${classOrName}" not found. Ensure the class has been imported.`);
+        }
+        ctor = found;
+    }
+    else {
+        // Class reference passed directly — ensure it's registered in the Registry
+        ctor = classOrName;
+        registry.registerClass(ctor);
+    }
+    // Return a factory function that loads all entities and hydrates them
+    const repo = registry.ensureRepository(ctor);
+    return () => repo.find().map((e) => Object.assign(new ctor(), e));
+});
+//# sourceMappingURL=Record.js.map

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

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

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

@@ -0,0 +1,20 @@
+import type { Record } from "./Record.js";
+/**
+ * Constructor signature for Record subclasses.
+ *
+ * Used as a generic constraint whenever SheetORM needs to refer to a
+ * class that can be `new`-ed and that carries the static `tableName`
+ * and `indexTableName` properties (e.g. in SheetRepository's generic
+ * parameter).
+ *
+ * @typeParam T - Concrete Record subclass type.
+ */
+export interface RecordConstructor<T extends Record = Record> {
+    /** Parameterless constructor — the ORM instantiates records via `new Ctor()`. */
+    new (): T;
+    /** Sheet tab name where the entity data is stored (e.g. "tbl_Cars"). */
+    tableName: string;
+    /** Sheet tab name for the combined secondary index (e.g. "idx_Cars"). */
+    indexTableName: string;
+}
+//# sourceMappingURL=RecordConstructor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RecordConstructor.d.ts","sourceRoot":"","sources":["../../../src/core/RecordConstructor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC1D,iFAAiF;IACjF,QAAQ,CAAC,CAAC;IAEV,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAElB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/npm/core/RecordConstructor.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=RecordConstructor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RecordConstructor.js","sourceRoot":"","sources":["../../../src/core/RecordConstructor.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,25 @@
+import type { Entity } from "./types/Entity.js";
+/**
+ * Type-erased static interface for Record classes.
+ *
+ * Similar to RecordConstructor but produces a generic Entity
+ * instead of a specific Record subclass. Used internally by
+ * Registry where the concrete type parameter is unknown.
+ */
+export interface RecordStatic {
+    /** Parameterless constructor producing an Entity instance. */
+    new (): Entity;
+    /** Sheet tab name for entity data (e.g. "tbl_Cars"). */
+    tableName: string;
+    /** Sheet tab name for the combined secondary index (e.g. "idx_Cars"). */
+    indexTableName: string;
+    /** JavaScript class name (used for Registry class-name lookup). */
+    name: string;
+    /** Whether the auto-created sheet should be protected. */
+    isProtected(): boolean;
+    /** Email addresses of editors allowed to edit the protected sheet. */
+    protectedFor(): string[];
+    /** Whether the auto-created sheet should be hidden from the tab bar. */
+    isHidden(): boolean;
+}
+//# sourceMappingURL=RecordStatic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RecordStatic.d.ts","sourceRoot":"","sources":["../../../src/core/RecordStatic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,QAAQ,MAAM,CAAC;IAEf,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAElB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;IAEvB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IAEb,0DAA0D;IAC1D,WAAW,IAAI,OAAO,CAAC;IAEvB,sEAAsE;IACtE,YAAY,IAAI,MAAM,EAAE,CAAC;IAEzB,wEAAwE;IACxE,QAAQ,IAAI,OAAO,CAAC;CACrB"}

package/dist/npm/core/RecordStatic.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=RecordStatic.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RecordStatic.js","sourceRoot":"","sources":["../../../src/core/RecordStatic.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,101 @@
+/**
+ * Global singleton registry that manages the ORM runtime state.
+ *
+ * Responsibilities:
+ * - Holds the single {@link ISpreadsheetAdapter} (defaults to GAS active spreadsheet).
+ * - Maintains a per-table {@link SheetRepository} cache so the same repo
+ *   is reused for the lifetime of the script execution.
+ * - Creates and wires up the shared {@link IndexStore} used by all repos.
+ * - Keeps a class map so `Query.from("ClassName")` can resolve by name.
+ *
+ * @module Registry
+ */
+import type { Entity } from "./types/Entity.js";
+import type { ICacheProvider } from "./types/ICacheProvider.js";
+import type { ISpreadsheetAdapter } from "./types/ISpreadsheetAdapter.js";
+import { SheetRepository } from "./SheetRepository.js";
+import { IndexStore } from "../index/IndexStore.js";
+import type { RecordStatic } from "./RecordStatic.js";
+/**
+ * Central registry for SheetORM.
+ *
+ * Accessed via `Registry.getInstance()`.  Call `Registry.reset()` in
+ * tests to start with a clean slate.
+ */
+export declare class Registry {
+    /** Singleton instance (lazy-initialised). */
+    private static instance;
+    /** The spreadsheet-level adapter (wraps GAS Spreadsheet or mock). */
+    private adapter;
+    /** Optional entity data cache (defaults to MemoryCache). */
+    private cache;
+    /** Shared secondary-index manager. */
+    private indexStore;
+    /** tableName → SheetRepository cache. */
+    private repos;
+    /** tableName → RecordStatic class map for lookup by table name. */
+    private classesByTable;
+    /** className → RecordStatic class map for lookup by constructor name. */
+    private classesByName;
+    /** Return (or create) the singleton Registry instance. */
+    static getInstance(): Registry;
+    /** Destroy the singleton — used by test suites to reset state between runs. */
+    static reset(): void;
+    /**
+     * Configure the registry with a custom adapter and/or cache.
+     * Clears all previously created repos, class maps, and the index store.
+     */
+    configure(options: {
+        adapter?: ISpreadsheetAdapter;
+        cache?: ICacheProvider;
+    }): void;
+    /**
+     * Return the current adapter, falling back to a default
+     * GoogleSpreadsheetAdapter (active spreadsheet) if none was configured.
+     */
+    private getAdapter;
+    /**
+     * Lazily create the shared IndexStore.
+     * The IndexStore receives its **own** MemoryCache instance so that
+     * `cache.clear()` inside it does not wipe the entity data cache.
+     */
+    private ensureIndexStore;
+    /**
+     * Ensure the sheet tab for a given schema exists, and register
+     * any declared secondary indexes with the IndexStore.
+     *
+     * @param schema     - The table schema (name, fields, indexes).
+     * @param indexStore - The shared IndexStore.
+     * @param ctor       - The Record subclass constructor (for protection config).
+     * @returns The sheet adapter and whether it was freshly created.
+     */
+    private ensureTable;
+    /**
+     * Register a Record subclass so it can be looked up by table name or
+     * class name via `getClassByName()`.
+     */
+    registerClass(ctor: RecordStatic): void;
+    /**
+     * Return (or create) the SheetRepository for a given Record subclass.
+     *
+     * On first call for a table name the method:
+     * 1. Registers the class in the class map.
+     * 2. Builds a {@link TableSchema} from decorator metadata.
+     * 3. Ensures the sheet tab exists (createSheet / insertSheet).
+     * 4. Creates a new SheetRepository with all optimisation flags
+     *    (L1 deferred headers, K2 index skipping, B5 known row count).
+     *
+     * Subsequent calls return the cached repository instance.
+     */
+    ensureRepository<T extends Entity>(ctor: RecordStatic): SheetRepository<T>;
+    /**
+     * Look up a previously registered Record subclass by constructor name
+     * or table name.
+     */
+    getClassByName(name: string): RecordStatic | undefined;
+    /** Return the shared IndexStore (creates it if needed). */
+    getIndexStore(): IndexStore;
+    /** Flush both the entity data cache and the index store caches. */
+    clearCache(): void;
+}
+//# sourceMappingURL=Registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Registry.d.ts","sourceRoot":"","sources":["../../../src/core/Registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAIpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB,6CAA6C;IAC7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAyB;IAEhD,qEAAqE;IACrE,OAAO,CAAC,OAAO,CAAoC;IACnD,4DAA4D;IAC5D,OAAO,CAAC,KAAK,CAA+B;IAC5C,sCAAsC;IACtC,OAAO,CAAC,UAAU,CAA2B;IAC7C,yCAAyC;IACzC,OAAO,CAAC,KAAK,CAA8C;IAC3D,mEAAmE;IACnE,OAAO,CAAC,cAAc,CAAmC;IACzD,yEAAyE;IACzE,OAAO,CAAC,aAAa,CAAmC;IAExD,0DAA0D;IAC1D,MAAM,CAAC,WAAW,IAAI,QAAQ;IAO9B,+EAA+E;IAC/E,MAAM,CAAC,KAAK,IAAI,IAAI;IAIpB;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,mBAAmB,CAAC;QAAC,KAAK,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI;IAUnF;;;OAGG;IACH,OAAO,CAAC,UAAU;IAOlB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAyEnB;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IASvC;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,eAAe,CAAC,CAAC,CAAC;IAkD1E;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAItD,2DAA2D;IAC3D,aAAa,IAAI,UAAU;IAI3B,mEAAmE;IACnE,UAAU,IAAI,IAAI;CAInB"}