@ensnode/ensdb-sdk 1.10.0 → 1.11.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { EnsIndexerPublicConfig, EnsDbPublicConfig, CrossChainIndexingStatusSnapshot, Unvalidated } from '@ensnode/ensnode-sdk';
+import { EnsDbPublicConfig, IndexingMetadataContext, IndexingMetadataContextInitialized, Unvalidated } from '@ensnode/ensnode-sdk';
+export { IndexingMetadataContext, IndexingMetadataContextInitialized, IndexingMetadataContextStatusCodes, IndexingMetadataContextUninitialized } from '@ensnode/ensnode-sdk';
 import { NodePgDatabase } from 'drizzle-orm/node-postgres';
-import { a as abstractEnsIndexerSchema } from './index-DN0SGSyd.js';
+import { a as abstractEnsIndexerSchema } from './index-C0lByZGy.js';
 import { e as ensNodeSchema } from './index-BHoa233Z.js';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm';
@@ -8,42 +9,20 @@ import 'ponder';
 import 'enssdk';
 
 /**
- * ENSDb Config
+ * Utilities for Drizzle ORM integration with ENSDb.
  */
-interface EnsDbConfig {
-    /**
-     * PostgreSQL connection string for ENSDb.
-     *
-     * Guaranteed to be a valid PostgreSQL connection string with the format:
-     * `postgresql://username:password@host:port/database` or
-     * `postgres://username:password@host:port/database`
-     */
-    ensDbUrl: string;
-    /**
-     * The name of the ENSIndexer Schema in the ENSDb instance.
-     *
-     * Guaranteed to be a non-empty string that is
-     * a valid Postgres database schema identifier
-     */
-    ensIndexerSchemaName: string;
-}
+
 /**
- * ENSDb Schema Checksum
+ * PostgreSQL startup `options` string for ENSDb connections.
  *
- * Checksum representing the ENSDb Schema definition, which is a combination of
- * - the ENSIndexer Schema definition, and
- * - the ENSNode Schema definition.
+ * Sets `search_path` so unqualified references (notably the `gin_trgm_ops`
+ * opclass from the pg_trgm extension, installed in the `ensnode` schema by
+ * migration 0001) resolve correctly at query and index-creation time.
  *
- * This checksum can be used to verify compatibility between
- * the ENSDb Schema definition expected by any client app connecting to ENSDb
- * instance and the actual ENSDb Schema definition present in ENSDb SDK.
+ * Pass via node-postgres `PoolConfig.options` (e.g. Ponder's
+ * `database.poolConfig.options`) or Drizzle's connection config.
  */
-declare const ENSDB_SCHEMA_CHECKSUM: string;
-
-/**
- * Utilities for Drizzle ORM integration with ENSDb.
- */
-
+declare const ENSDB_CONNECTION_OPTIONS = "-c search_path=ensnode,public";
 /**
  * Abstract ENSIndexer Schema
  *
@@ -73,6 +52,39 @@ type EnsDbSchema<ConcreteEnsIndexerSchema extends AbstractEnsIndexerSchema> = Co
  */
 type EnsDbDrizzleClient<ConcreteEnsIndexerSchema extends AbstractEnsIndexerSchema> = NodePgDatabase<EnsDbSchema<ConcreteEnsIndexerSchema>>;
 
+/**
+ * ENSDb Config
+ */
+interface EnsDbConfig {
+    /**
+     * PostgreSQL connection string for ENSDb.
+     *
+     * Guaranteed to be a valid PostgreSQL connection string with the format:
+     * `postgresql://username:password@host:port/database` or
+     * `postgres://username:password@host:port/database`
+     */
+    ensDbUrl: string;
+    /**
+     * The name of the ENSIndexer Schema in the ENSDb instance.
+     *
+     * Guaranteed to be a non-empty string that is
+     * a valid Postgres database schema identifier
+     */
+    ensIndexerSchemaName: string;
+}
+/**
+ * ENSDb Schema Checksum
+ *
+ * Checksum representing the ENSDb Schema definition, which is a combination of
+ * - the ENSIndexer Schema definition, and
+ * - the ENSNode Schema definition.
+ *
+ * This checksum can be used to verify compatibility between
+ * the ENSDb Schema definition expected by any client app connecting to ENSDb
+ * instance and the actual ENSDb Schema definition present in ENSDb SDK.
+ */
+declare const ENSDB_SCHEMA_CHECKSUM: string;
+
 /**
  * ENSDb Reader
  *
@@ -141,27 +153,26 @@ declare class EnsDbReader<ConcreteEnsIndexerSchema extends AbstractEnsIndexerSch
      */
     get ensNodeSchema(): EnsNodeSchema;
     /**
-     * Get ENSDb Version
-     *
-     * @returns the existing record, or `undefined`.
+     * Check if the ENSDb instance is healthy by running a simple query
+     * against it.
      */
-    getEnsDbVersion(): Promise<string | undefined>;
+    isHealthy(): Promise<boolean>;
     /**
-     * Get ENSIndexer Public Config
-     *
-     * @returns the existing record, or `undefined`.
+     * Check if the ENSDb instance is ready by verifying that
+     * the {@link IndexingMetadataContext} has been initialized for
+     * the ENSIndexer Schema used by this ENSDbReader instance.
      */
-    getEnsIndexerPublicConfig(): Promise<EnsIndexerPublicConfig | undefined>;
+    isReady(): Promise<boolean>;
     /**
      * Build ENSDb Public Config
      */
     buildEnsDbPublicConfig(): Promise<EnsDbPublicConfig>;
     /**
-     * Get Indexing Status Snapshot
+     * Get Indexing Metadata Context
      *
-     * @returns the existing record, or `undefined`.
+     * @returns the initialized record, or a default uninitialized one if no record exists in ENSDb.
      */
-    getIndexingStatusSnapshot(): Promise<CrossChainIndexingStatusSnapshot | undefined>;
+    getIndexingMetadataContext(): Promise<IndexingMetadataContext>;
     /**
      * Get ENSNode Metadata record
      *
@@ -194,32 +205,31 @@ declare class EnsDbReader<ConcreteEnsIndexerSchema extends AbstractEnsIndexerSch
  * - updating ENSNode Metadata records in ENSDb for the given ENSIndexer instance.
  */
 declare class EnsDbWriter extends EnsDbReader {
+    /**
+     * Stable arbitrary lock ID for ENSNode Schema migrations to
+     * prevent concurrent migration execution across multiple ENSIndexer instances.
+     */
+    private static readonly MIGRATION_LOCK_ID;
     /**
      * Execute pending database migrations for ENSNode Schema in ENSDb.
      *
+     * This function is:
+     * - idempotent and can be safely executed multiple times,
+     * - safe to execute concurrently across multiple ENSIndexer instances,
+     *   as it uses a stable arbitrary advisory lock to prevent concurrent
+     *   execution of migrations.
+     *
      * @param migrationsDirPath - The file path to the directory containing
      *                            database migration files for ENSNode Schema.
      * @throws error when migration execution fails.
      */
     migrateEnsNodeSchema(migrationsDirPath: string): Promise<void>;
     /**
-     * Upsert ENSDb Version
+     * Upsert Indexing Metadata Context Initialized
      *
      * @throws when upsert operation failed.
      */
-    upsertEnsDbVersion(ensDbVersion: string): Promise<void>;
-    /**
-     * Upsert ENSIndexer Public Config
-     *
-     * @throws when upsert operation failed.
-     */
-    upsertEnsIndexerPublicConfig(ensIndexerPublicConfig: EnsIndexerPublicConfig): Promise<void>;
-    /**
-     * Upsert Indexing Status Snapshot
-     *
-     * @throws when upsert operation failed.
-     */
-    upsertIndexingStatusSnapshot(indexingStatus: CrossChainIndexingStatusSnapshot): Promise<void>;
+    upsertIndexingMetadataContext(indexingMetadataContext: IndexingMetadataContextInitialized): Promise<void>;
     /**
      * Upsert ENSNode metadata
      *
@@ -232,29 +242,28 @@ declare class EnsDbWriter extends EnsDbReader {
  * Keys used to distinguish records in `ensnode_metadata` table in the ENSDb.
  */
 declare const EnsNodeMetadataKeys: {
-    readonly EnsDbVersion: "ensdb_version";
-    readonly EnsIndexerPublicConfig: "ensindexer_public_config";
-    readonly EnsIndexerIndexingStatus: "ensindexer_indexing_status";
+    readonly IndexingMetadataContext: "indexing_metadata_context";
 };
 type EnsNodeMetadataKey = (typeof EnsNodeMetadataKeys)[keyof typeof EnsNodeMetadataKeys];
-interface EnsNodeMetadataEnsDbVersion {
-    key: typeof EnsNodeMetadataKeys.EnsDbVersion;
-    value: string;
-}
-interface EnsNodeMetadataEnsIndexerPublicConfig {
-    key: typeof EnsNodeMetadataKeys.EnsIndexerPublicConfig;
-    value: EnsIndexerPublicConfig;
-}
-interface EnsNodeMetadataEnsIndexerIndexingStatus {
-    key: typeof EnsNodeMetadataKeys.EnsIndexerIndexingStatus;
-    value: CrossChainIndexingStatusSnapshot;
+/**
+ * ENSNode Metadata record for Indexing Metadata Context
+ *
+ * This record is used to store the Indexing Metadata Context in
+ * ENSNode Metadata table for each ENSIndexer instance.
+ */
+interface EnsNodeMetadataIndexingMetadataContext {
+    key: typeof EnsNodeMetadataKeys.IndexingMetadataContext;
+    value: IndexingMetadataContextInitialized;
 }
 /**
  * ENSNode Metadata
  *
- * Union type gathering all variants of ENSNode Metadata.
+ * Type alias for ENSNode Metadata records,
+ * currently only includes the record for Indexing Metadata Context,
+ * but can be extended in the future to include more types of
+ * ENSNode Metadata records as needed.
  */
-type EnsNodeMetadata = EnsNodeMetadataEnsDbVersion | EnsNodeMetadataEnsIndexerPublicConfig | EnsNodeMetadataEnsIndexerIndexingStatus;
+type EnsNodeMetadata = EnsNodeMetadataIndexingMetadataContext;
 
 /**
  * Validate ENSDb config
@@ -265,4 +274,4 @@ type EnsNodeMetadata = EnsNodeMetadataEnsDbVersion | EnsNodeMetadataEnsIndexerPu
  */
 declare function validateEnsDbConfig(unvalidatedConfig: Unvalidated<EnsDbConfig>): EnsDbConfig;
 
-export { ENSDB_SCHEMA_CHECKSUM, type EnsDbConfig, type EnsDbDrizzleClient, EnsDbReader, EnsDbWriter, type EnsNodeMetadata, type EnsNodeMetadataEnsDbVersion, type EnsNodeMetadataEnsIndexerIndexingStatus, type EnsNodeMetadataEnsIndexerPublicConfig, type EnsNodeMetadataKey, EnsNodeMetadataKeys, validateEnsDbConfig };
+export { ENSDB_CONNECTION_OPTIONS, ENSDB_SCHEMA_CHECKSUM, type EnsDbConfig, type EnsDbDrizzleClient, EnsDbReader, EnsDbWriter, type EnsNodeMetadata, type EnsNodeMetadataIndexingMetadataContext, type EnsNodeMetadataKey, EnsNodeMetadataKeys, validateEnsDbConfig };