gitsheets 0.22.4 → 1.0.3

package/dist/push-daemon.js.map

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

package/dist/repository.d.ts

@@ -0,0 +1,67 @@
+import { Repo as HologitRepo } from 'hologit';
+import type { RecordLike } from './path-template/index.js';
+import { PushDaemon, type PushDaemonOptions } from './push-daemon.js';
+import { Sheet } from './sheet.js';
+import { type TransactionHandler, type TransactionOptions, type TransactionResult } from './transaction.js';
+import type { StandardSchemaV1 } from './validation.js';
+export interface OpenRepoOptions {
+    /** Path to a `.git` directory. If omitted, discovered from the cwd upward. */
+    readonly gitDir?: string;
+    /** Working tree path; default `null` (bare-style operation). */
+    readonly workTree?: string | null;
+}
+export interface OpenSheetOptions<T extends RecordLike = RecordLike> {
+    /** Sub-directory under the data tree to scope this sheet to; default '.'. */
+    readonly root?: string;
+    /** Standard Schema validator; runs after the persisted JSON Schema. */
+    readonly validator?: StandardSchemaV1<unknown, T>;
+}
+/** Options for {@link Repository.openSheets}. No `validator` — use {@link openStore} for that. */
+export interface OpenSheetsOptions {
+    /** Sub-directory under the data tree to scope every sheet to; default '.'. */
+    readonly root?: string;
+}
+export declare class Repository {
+    #private;
+    constructor(hologitRepo: HologitRepo);
+    /** Discover a `.git` upward from `cwd` and open it. */
+    static fromCwd(): Promise<Repository>;
+    /** Open a specific git directory. */
+    static open(opts: OpenRepoOptions): Promise<Repository>;
+    /**
+     * @internal — Direct access to the underlying hologit substrate is reserved
+     * for the library. Consumers should use the public Repository surface; the
+     * substrate is an implementation detail and will swap to Rust holo-tree in
+     * v1.1 with no public-API change ([#127]).
+     */
+    get hologitRepo(): HologitRepo;
+    get gitDir(): string;
+    /** @internal — used by Sheet to enforce strict mode. Library cross-class signal, not a consumer API. */
+    isStrictMode(): boolean;
+    /** Switch to strict mode — mutations outside repo.transact throw. One-way. */
+    requireExplicitTransactions(): void;
+    /** Resolve a ref or commit hash. Returns the full commit hash or null. */
+    resolveRef(ref: string): Promise<string | null>;
+    /**
+     * Open a Sheet handle bound to the workspace at the resolved ref (default
+     * HEAD). Throws ConfigError(config_missing) when `.gitsheets/<name>.toml`
+     * is absent.
+     */
+    openSheet<T extends RecordLike = RecordLike>(name: string, opts?: OpenSheetOptions<T>): Promise<Sheet<T>>;
+    /** Discover every sheet declared in `<root>/.gitsheets/*.toml`. */
+    openSheets(opts?: OpenSheetsOptions): Promise<Record<string, Sheet>>;
+    /**
+     * Run a handler inside a transaction. On handler success, commit; on throw,
+     * discard the tree. See specs/api/transaction.md.
+     */
+    transact<T>(opts: TransactionOptions, handler: TransactionHandler<T>): Promise<TransactionResult<T>>;
+    /**
+     * Start an async push daemon for this repo. Only one daemon may be active
+     * at a time; throws TransactionError(push_daemon_running) on contention.
+     * See specs/behaviors/push-sync.md.
+     */
+    startPushDaemon(opts: PushDaemonOptions): Promise<PushDaemon>;
+}
+/** Convenience factory: `openRepo({ gitDir? })`. */
+export declare function openRepo(opts?: OpenRepoOptions): Promise<Repository>;
+//# sourceMappingURL=repository.d.ts.map

package/dist/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../src/repository.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AAI9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EACL,UAAU,EAEV,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IACjE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;CACnD;AAED,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,UAAU;;gBAOT,WAAW,EAAE,WAAW;IAIpC,uDAAuD;WAC1C,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IAK3C,qCAAqC;WACxB,IAAI,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAY7D;;;;;OAKG;IACH,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,wGAAwG;IACxG,YAAY,IAAI,OAAO;IAIvB,8EAA8E;IAC9E,2BAA2B,IAAI,IAAI;IAInC,0EAA0E;IACpE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIrD;;;;OAIG;IACG,SAAS,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EAC/C,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,gBAAgB,CAAC,CAAC,CAAM,GAC7B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAqBpB,mEAAmE;IAC7D,UAAU,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IA4B9E;;;OAGG;IACG,QAAQ,CAAC,CAAC,EACd,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IA6DhC;;;;OAIG;IACG,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;CA2JpE;AAED,oDAAoD;AACpD,wBAAsB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAE9E"}

package/dist/repository.js

@@ -0,0 +1,322 @@
+// Repository — entry point. Wraps hologit's Repo with gitsheets-specific
+// orchestration (transactions, sheet discovery). See specs/api/repository.md.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { Repo as HologitRepo } from 'hologit';
+import { ConfigError, RefError, TransactionError } from './errors.js';
+import { PushDaemon, resolveBackoff, } from './push-daemon.js';
+import { Sheet } from './sheet.js';
+import { Mutex, Transaction, resolveAuthor, transactionContext, } from './transaction.js';
+const exec = promisify(execFile);
+export class Repository {
+    #hologitRepo;
+    #mutex = new Mutex();
+    #postCommitHooks = [];
+    #strictMode = false;
+    #pushDaemon = null;
+    constructor(hologitRepo) {
+        this.#hologitRepo = hologitRepo;
+    }
+    /** Discover a `.git` upward from `cwd` and open it. */
+    static async fromCwd() {
+        const repo = await HologitRepo.getFromEnvironment();
+        return new Repository(repo);
+    }
+    /** Open a specific git directory. */
+    static async open(opts) {
+        if (!opts.gitDir) {
+            return Repository.fromCwd();
+        }
+        const repoOpts = { gitDir: opts.gitDir };
+        if (opts.workTree !== undefined) {
+            repoOpts.workTree = opts.workTree;
+        }
+        const repo = new HologitRepo(repoOpts);
+        return new Repository(repo);
+    }
+    /**
+     * @internal — Direct access to the underlying hologit substrate is reserved
+     * for the library. Consumers should use the public Repository surface; the
+     * substrate is an implementation detail and will swap to Rust holo-tree in
+     * v1.1 with no public-API change ([#127]).
+     */
+    get hologitRepo() {
+        return this.#hologitRepo;
+    }
+    get gitDir() {
+        return this.#hologitRepo.gitDir;
+    }
+    /** @internal — used by Sheet to enforce strict mode. Library cross-class signal, not a consumer API. */
+    isStrictMode() {
+        return this.#strictMode;
+    }
+    /** Switch to strict mode — mutations outside repo.transact throw. One-way. */
+    requireExplicitTransactions() {
+        this.#strictMode = true;
+    }
+    /** Resolve a ref or commit hash. Returns the full commit hash or null. */
+    async resolveRef(ref) {
+        return this.#hologitRepo.resolveRef(ref);
+    }
+    /**
+     * Open a Sheet handle bound to the workspace at the resolved ref (default
+     * HEAD). Throws ConfigError(config_missing) when `.gitsheets/<name>.toml`
+     * is absent.
+     */
+    async openSheet(name, opts = {}) {
+        const root = opts.root ?? '.';
+        const workspace = await this.#getWorkspace();
+        const dataTree = await this.#resolveDataTree(workspace, root);
+        const configPath = joinTreePath(root, '.gitsheets', `${name}.toml`);
+        const sheetOpts = {
+            repo: this,
+            workspace,
+            dataTree,
+            name,
+            configPath,
+        };
+        if (opts.validator !== undefined) {
+            Object.assign(sheetOpts, { validator: opts.validator });
+        }
+        const sheet = new Sheet(sheetOpts);
+        // Eagerly validate config exists by reading once.
+        await sheet.readConfig();
+        return sheet;
+    }
+    /** Discover every sheet declared in `<root>/.gitsheets/*.toml`. */
+    async openSheets(opts = {}) {
+        const root = opts.root ?? '.';
+        const workspace = await this.#getWorkspace();
+        const sheetsDir = await workspace.root.getSubtree(joinTreePath(root, '.gitsheets'));
+        if (!sheetsDir)
+            return {};
+        const children = await sheetsDir.getChildren();
+        const out = {};
+        const dataTree = await this.#resolveDataTree(workspace, root);
+        // for...in to include hologit's prototype-loaded entries.
+        for (const childName in children) {
+            const child = children[childName];
+            const match = /^(.+)\.toml$/.exec(childName);
+            if (!match)
+                continue;
+            if (!child || child.isBlob !== true)
+                continue;
+            const sheetName = match[1];
+            out[sheetName] = new Sheet({
+                repo: this,
+                workspace,
+                dataTree,
+                name: sheetName,
+                configPath: joinTreePath(root, '.gitsheets', childName),
+            });
+        }
+        return out;
+    }
+    /**
+     * Run a handler inside a transaction. On handler success, commit; on throw,
+     * discard the tree. See specs/api/transaction.md.
+     */
+    async transact(opts, handler) {
+        if (transactionContext.getStore() !== undefined) {
+            throw new TransactionError('transaction_in_progress', 'nested repo.transact is not allowed — use tx.sheet(name) inside the handler');
+        }
+        const normalized = Transaction.normalizeOptions(opts);
+        const author = await resolveAuthor(this.gitDir, normalized.author);
+        const committer = normalized.committer ?? author;
+        const release = await this.#mutex.acquire();
+        try {
+            const { parent, branch } = await this.#resolveParent(normalized.parent, normalized.branch);
+            const parentCommitHash = parent.commitHash;
+            const workspace = parentCommitHash
+                ? await this.#hologitRepo.createWorkspaceFromRef(parentCommitHash)
+                : await this.#emptyWorkspace();
+            const tx = new Transaction({
+                hologitRepo: this.#hologitRepo,
+                workspace,
+                parentCommitHash,
+                parentRef: parent.refName,
+                branchRef: branch,
+                author,
+                committer,
+                message: normalized.message,
+                trailers: normalized.trailers,
+                sheetFactory: (name, ws, tree, validator) => this.#makeTxSheet(tx, name, ws, tree, validator),
+            });
+            let value;
+            try {
+                value = await transactionContext.run(tx, () => handler(tx));
+            }
+            catch (err) {
+                tx.discard();
+                throw err;
+            }
+            const result = await tx.finalize(value);
+            if (result.commitHash !== null) {
+                for (const hook of this.#postCommitHooks) {
+                    try {
+                        hook(result.commitHash);
+                    }
+                    catch {
+                        // Hooks must not break transactions.
+                    }
+                }
+            }
+            return result;
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Start an async push daemon for this repo. Only one daemon may be active
+     * at a time; throws TransactionError(push_daemon_running) on contention.
+     * See specs/behaviors/push-sync.md.
+     */
+    async startPushDaemon(opts) {
+        if (this.#pushDaemon) {
+            throw new TransactionError('push_daemon_running', 'a push daemon is already running for this Repository — stop it first');
+        }
+        let branch = opts.branch;
+        if (!branch) {
+            const headRef = await this.#headBranchRef();
+            if (!headRef) {
+                throw new RefError('ref_not_found', 'cannot start push daemon — HEAD is detached or the repo is fresh');
+            }
+            branch = headRef.replace(/^refs\/heads\//, '');
+        }
+        const daemon = new PushDaemon({
+            gitDir: this.gitDir,
+            remote: opts.remote,
+            branch,
+            backoff: resolveBackoff(opts.backoff),
+            maxRetries: opts.maxRetries ?? Number.POSITIVE_INFINITY,
+        });
+        this.#pushDaemon = daemon;
+        const hook = (commitHash) => daemon.notifyCommit(commitHash);
+        this.#postCommitHooks.push(hook);
+        daemon.once('stopped', () => {
+            const idx = this.#postCommitHooks.indexOf(hook);
+            if (idx >= 0)
+                this.#postCommitHooks.splice(idx, 1);
+            this.#pushDaemon = null;
+        });
+        return daemon;
+    }
+    // --- Private helpers ---
+    #makeTxSheet(tx, name, workspace, tree, validator) {
+        const configPath = `.gitsheets/${name}.toml`;
+        const opts = {
+            repo: this,
+            workspace,
+            dataTree: tree,
+            name,
+            configPath,
+            transaction: tx,
+        };
+        if (validator !== undefined)
+            Object.assign(opts, { validator });
+        return new Sheet(opts);
+    }
+    async #getWorkspace() {
+        // Bypass hologit's getWorkspace cache — it caches the first observed
+        // workspace per Repo instance, so post-commit reads would return stale
+        // state. Resolve HEAD fresh on each call. Fresh-repo fallback handles #19.
+        let head = null;
+        try {
+            head = await this.#hologitRepo.resolveRef('HEAD');
+        }
+        catch {
+            head = null;
+        }
+        if (head) {
+            return this.#hologitRepo.createWorkspaceFromRef(head);
+        }
+        return this.#emptyWorkspace();
+    }
+    async #emptyWorkspace() {
+        // hologit doesn't expose an empty-workspace factory directly. Use the
+        // empty-tree hash to bootstrap a workspace from a deterministic tree.
+        const { TreeObject } = await import('hologit');
+        const emptyTreeHash = TreeObject.getEmptyTreeHash();
+        return this.#hologitRepo.createWorkspaceFromTreeHash(emptyTreeHash);
+    }
+    async #resolveDataTree(workspace, root) {
+        if (root === '.' || root === '')
+            return workspace.root;
+        const sub = await workspace.root.getSubtree(root, true);
+        if (!sub) {
+            throw new ConfigError('config_missing', `data root ${root} not found in workspace`);
+        }
+        return sub;
+    }
+    /**
+     * Resolve the parent ref + branch ref pair per specs/behaviors/transactions.md.
+     * - parent unset → HEAD's branch (or detached HEAD's commit)
+     * - parent = branch → branch advances
+     * - parent = hash → no ref updated unless `branch` explicit
+     */
+    async #resolveParent(parent, branch) {
+        if (!parent) {
+            // Use HEAD's branch when on a branch; otherwise current HEAD commit.
+            const headRef = await this.#headBranchRef();
+            if (headRef) {
+                const commit = await this.#hologitRepo.resolveRef(headRef);
+                return {
+                    parent: { refName: headRef, commitHash: commit },
+                    branch: branch ?? headRef,
+                };
+            }
+            // Detached or fresh repo
+            const headHash = await this.#hologitRepo.resolveRef('HEAD').catch(() => null);
+            return {
+                parent: { refName: null, commitHash: headHash },
+                branch: branch ?? null,
+            };
+        }
+        // parent is set — figure out if it's a ref name (branch) or a hash
+        const isLikelyBranch = /^[a-zA-Z0-9_./-]+$/.test(parent) && !/^[0-9a-f]{4,40}$/.test(parent);
+        if (isLikelyBranch) {
+            const refName = parent.startsWith('refs/') ? parent : `refs/heads/${parent}`;
+            const commit = await this.#hologitRepo.resolveRef(refName);
+            if (commit === null) {
+                // Maybe they passed a raw "main" that doesn't exist yet
+                throw new RefError('ref_not_found', `ref not found: ${parent}`);
+            }
+            return {
+                parent: { refName, commitHash: commit },
+                branch: branch ?? refName,
+            };
+        }
+        // Hash
+        const resolved = await this.#hologitRepo.resolveRef(parent);
+        if (!resolved) {
+            throw new RefError('ref_not_found', `cannot resolve commit: ${parent}`);
+        }
+        return {
+            parent: { refName: null, commitHash: resolved },
+            branch: branch ? (branch.startsWith('refs/') ? branch : `refs/heads/${branch}`) : null,
+        };
+    }
+    async #headBranchRef() {
+        try {
+            const { stdout } = await exec('git', ['symbolic-ref', '--quiet', 'HEAD'], {
+                cwd: this.gitDir,
+            });
+            return stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Convenience factory: `openRepo({ gitDir? })`. */
+export async function openRepo(opts = {}) {
+    return Repository.open(opts);
+}
+function joinTreePath(...parts) {
+    return parts
+        .map((p) => p.replace(/^\/+/, '').replace(/\/+$/, ''))
+        .filter((p) => p.length > 0 && p !== '.')
+        .join('/');
+}
+//# sourceMappingURL=repository.js.map

package/dist/repository.js.map

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

package/dist/sheet.d.ts

@@ -0,0 +1,107 @@
+import type { BlobObject, TreeObject, Workspace } from 'hologit';
+import { type RecordLike } from './path-template/index.js';
+import type { Repository } from './repository.js';
+import { Transaction } from './transaction.js';
+import { type JSONSchema, type StandardSchemaV1 } from './validation.js';
+export declare const RECORD_SHEET_KEY: unique symbol;
+export declare const RECORD_PATH_KEY: unique symbol;
+export type SortRule = boolean | readonly string[] | Readonly<Record<string, 'ASC' | 'DESC'>> | string;
+export interface SheetFieldConfig {
+    /** Optional sort rule for array-valued fields (canonical normalization). */
+    readonly sort?: SortRule;
+}
+export interface SheetConfig {
+    readonly root: string;
+    readonly path: string;
+    readonly fields: Readonly<Record<string, SheetFieldConfig>>;
+    /** JSON Schema for record validation; null if no [gitsheet.schema] block. */
+    readonly schema: JSONSchema | null;
+}
+export interface UpsertResult {
+    readonly blob: BlobObject;
+    readonly path: string;
+}
+/**
+ * Filter passed to `Sheet.query` / `queryFirst` / `queryAll`. Each field's
+ * value can be a literal (equality match) or a predicate function. When `T`
+ * is `Record<string, unknown>` (the default), arbitrary string keys are
+ * accepted; consumer-supplied `T` narrows to its own keys.
+ */
+export type QueryFilter<T extends RecordLike = RecordLike> = {
+    [K in keyof T]?: T[K] | ((value: T[K], record: T) => unknown);
+};
+export type IndexKeyFn<T extends RecordLike = RecordLike> = (record: T) => string | undefined | null;
+export interface DefineIndexOptions {
+    readonly unique?: boolean;
+    readonly eager?: boolean;
+}
+export interface SheetConstructorOptions<T extends RecordLike = RecordLike> {
+    readonly repo: Repository;
+    readonly workspace: Workspace;
+    readonly dataTree: TreeObject;
+    readonly name: string;
+    readonly configPath: string;
+    readonly transaction?: Transaction;
+    /** Consumer-supplied Standard Schema validator; runs after JSON Schema. */
+    readonly validator?: StandardSchemaV1<unknown, T>;
+}
+export declare class Sheet<T extends RecordLike = RecordLike> {
+    #private;
+    constructor(opts: SheetConstructorOptions<T>);
+    get name(): string;
+    get configPath(): string;
+    /** True if this Sheet is bound to a transaction's private tree. */
+    get isTransactionBound(): boolean;
+    readConfig(): Promise<SheetConfig>;
+    /** Same as readConfig — config is cached by config-blob hash anyway. */
+    getCachedConfig(): Promise<SheetConfig>;
+    /** Async iterator over records matching the filter. */
+    query(filter?: QueryFilter<T>): AsyncGenerator<T>;
+    queryFirst(filter?: QueryFilter<T>): Promise<T | undefined>;
+    queryAll(filter?: QueryFilter<T>): Promise<T[]>;
+    pathForRecord(record: T): Promise<string>;
+    /**
+     * Apply canonical normalization (deep key sort + array-field sort rules)
+     * without writing or validating.
+     */
+    normalizeRecord(record: T): Promise<T>;
+    clear(): Promise<void>;
+    clone(): Promise<Sheet<T>>;
+    upsert(record: T): Promise<UpsertResult>;
+    /**
+     * RFC 7396 JSON Merge Patch. Reads the matching record, merges `partial`,
+     * validates, and upserts the result. Returns the same shape as upsert.
+     * Throws NotFoundError if the query matches no record.
+     */
+    patch(query: QueryFilter<T>, partial: Partial<T>): Promise<UpsertResult>;
+    delete(target: T | string): Promise<void>;
+    /**
+     * Declare a secondary in-memory index on this Sheet.
+     *
+     * Overloads:
+     *   defineIndex(name, keyFn) → void
+     *   defineIndex(name, { unique?, eager?: false }, keyFn) → void
+     *   defineIndex(name, { unique?, eager: true }, keyFn)   → Promise<void>
+     *
+     * keyFn returns a string key; returning undefined / null excludes the
+     * record from the index entirely. With `eager: true`, the return value
+     * resolves when the initial build completes (or rejects on conflict).
+     */
+    defineIndex(name: string, keyFn: IndexKeyFn<T>): void;
+    defineIndex(name: string, opts: DefineIndexOptions & {
+        eager: true;
+    }, keyFn: IndexKeyFn<T>): Promise<void>;
+    defineIndex(name: string, opts: DefineIndexOptions & {
+        eager?: false | undefined;
+    }, keyFn: IndexKeyFn<T>): void;
+    /**
+     * Look up records by an index. Unique indexes return `record | undefined`;
+     * non-unique indexes return an array.
+     */
+    findByIndex(name: string, key: string): Promise<T | T[] | undefined>;
+    getAttachment(record: T | string, name: string): Promise<BlobObject | null>;
+    getAttachments(record: T | string): Promise<Record<string, BlobObject> | null>;
+    setAttachment(record: T | string, name: string, blob: string | BlobObject): Promise<void>;
+    setAttachments(record: T | string, attachments: Record<string, string | BlobObject>): Promise<void>;
+}
+//# sourceMappingURL=sheet.d.ts.map

package/dist/sheet.d.ts.map

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