@secondlayer/subgraphs 0.5.0

package/dist/src/index.d.ts

@@ -0,0 +1,219 @@
+/** Supported column types for subgraph schemas */
+type ColumnType = "text" | "uint" | "int" | "principal" | "boolean" | "timestamp" | "jsonb";
+/** Column definition in a subgraph table */
+interface SubgraphColumn {
+	type: ColumnType;
+	nullable?: boolean;
+	indexed?: boolean;
+	search?: boolean;
+	default?: string | number | boolean;
+}
+/** Table definition within a subgraph schema */
+interface SubgraphTable {
+	columns: Record<string, SubgraphColumn>;
+	/** Composite indexes (each entry is an array of column names) */
+	indexes?: string[][];
+	/** Unique key constraints (each entry is an array of column names). Required for upsert. */
+	uniqueKeys?: string[][];
+}
+/** Subgraph schema — maps table names to table definitions */
+type SubgraphSchema = Record<string, SubgraphTable>;
+/** Source filter for what blockchain data this subgraph processes */
+interface SubgraphSource {
+	/** Contract principal (e.g., SP000...::contract-name). Supports * wildcards. */
+	contract?: string;
+	/** Event name/topic to filter on */
+	event?: string;
+	/** Function name to filter on */
+	function?: string;
+	/** Transaction type filter (e.g., "stx_transfer", "contract_call") */
+	type?: string;
+	/** Minimum amount filter (for stx_transfer sources) */
+	minAmount?: bigint;
+}
+/** Context passed to subgraph handlers during event processing */
+interface SubgraphContext {
+	block: {
+		height: number
+		hash: string
+		timestamp: number
+		burnBlockHeight: number
+	};
+	tx: {
+		txId: string
+		sender: string
+		type: string
+		status: string
+	};
+	insert(table: string, row: Record<string, unknown>): void;
+	update(table: string, where: Record<string, unknown>, set: Record<string, unknown>): void;
+	upsert(table: string, key: Record<string, unknown>, row: Record<string, unknown>): void;
+	delete(table: string, where: Record<string, unknown>): void;
+	findOne(table: string, where: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+	findMany(table: string, where: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+}
+/** Handler function that processes events and writes to the subgraph */
+type SubgraphHandler = (event: Record<string, unknown>, ctx: SubgraphContext) => Promise<void> | void;
+/**
+* Derive the source key used to look up handlers.
+* - { contract: "SP123.market", function: "list" } → "SP123.market::list"
+* - { contract: "SP123.market", event: "sale" } → "SP123.market::sale"
+* - { contract: "SP123.market" } → "SP123.market"
+* - { type: "stx_transfer" } → "stx_transfer"
+*/
+declare function sourceKey(source: SubgraphSource): string;
+/** Complete subgraph definition */
+interface SubgraphDefinition {
+	/** Unique subgraph name (lowercase, alphanumeric + hyphens) */
+	name: string;
+	/** Semantic version */
+	version?: string;
+	/** Human description */
+	description?: string;
+	/** What blockchain data to process — one or more source filters */
+	sources: SubgraphSource[];
+	/** Tables in this subgraph */
+	schema: SubgraphSchema;
+	/** Keyed handler functions — keys match sourceKey() output, "*" is catch-all */
+	handlers: Record<string, SubgraphHandler>;
+}
+/**
+* Validates a subgraph definition, returning the parsed result or throwing on failure.
+*/
+declare function validateSubgraphDefinition(def: unknown): SubgraphDefinition;
+interface ReindexOptions {
+	fromBlock?: number;
+	toBlock?: number;
+	schemaName?: string;
+}
+/**
+* Reindex a subgraph by dropping its tables, recreating them, and reprocessing
+* all historical blocks through the handler pipeline.
+*/
+declare function reindexSubgraph(def: SubgraphDefinition, opts?: ReindexOptions): Promise<{
+	processed: number
+}>;
+/**
+* Identity function that preserves schema literal types for type inference.
+*
+* The generic `S` is narrowed to the exact schema shape so that column type
+* literals (e.g. `"uint"`) are preserved rather than widened to `string`.
+*
+* @example
+* ```ts
+* defineSubgraph({
+*   name: "my-subgraph",
+*   sources: [{ contract: "SP000...::my-contract" }],
+*   schema: { transfers: { columns: { amount: { type: "uint" } } } },
+*   handlers: { "*": (event, ctx) => { ... } }
+* })
+* // typeof result.schema.transfers.columns.amount.type → "uint" (not string)
+* ```
+*/
+declare function defineSubgraph<S extends SubgraphSchema>(def: Omit<SubgraphDefinition, "schema"> & {
+	schema: S
+}): Omit<SubgraphDefinition, "schema"> & {
+	schema: S
+};
+interface GeneratedSQL {
+	statements: string[];
+	hash: string;
+}
+/**
+* Generates PostgreSQL DDL statements for a subgraph definition.
+* Creates a dedicated schema `subgraph_<name>` with one table per schema entry,
+* each with auto-columns and indexes.
+*/
+declare function generateSubgraphSQL(def: SubgraphDefinition, schemaNameOverride?: string): GeneratedSQL;
+import { pgSchemaName } from "@secondlayer/shared/db/queries/subgraphs";
+import { Kysely } from "kysely";
+import { Database } from "@secondlayer/shared/db";
+type AnyDb = Kysely<Database>;
+interface TableDiff {
+	/** Tables added to the schema */
+	addedTables: string[];
+	/** Tables removed from the schema */
+	removedTables: string[];
+	/** Per-table column diffs (only for tables present in both) */
+	tables: Record<string, ColumnDiff>;
+}
+interface ColumnDiff {
+	added: string[];
+	removed: string[];
+	changed: string[];
+}
+/**
+* Compare two multi-table subgraph schemas and return differences.
+*/
+declare function diffSchema(existing: SubgraphSchema, incoming: SubgraphSchema): TableDiff;
+/**
+* Deploy a subgraph schema to the database.
+* - New subgraph → CREATE SCHEMA + tables + register
+* - Same hash → no-op
+* - Additive change → ALTER TABLE ADD COLUMN / CREATE TABLE for new tables
+* - Breaking change → throws error
+*/
+declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: string, opts?: {
+	forceReindex?: boolean
+	apiKeyId?: string
+	schemaName?: string
+}): Promise<{
+	action: "created" | "unchanged" | "updated" | "reindexed"
+	subgraphId: string
+}>;
+/** Maps a ColumnType string literal to its TypeScript equivalent */
+type ColumnToTS<T extends string> = T extends "uint" | "int" ? number : T extends "text" | "principal" | "timestamp" ? string : T extends "boolean" ? boolean : T extends "jsonb" ? Record<string, unknown> : unknown;
+/** Infer TS type for a single column definition, respecting nullable */
+type InferColumnType<C extends SubgraphColumn> = C["type"] extends ColumnType ? C["nullable"] extends true ? ColumnToTS<C["type"]> | null : ColumnToTS<C["type"]> : unknown;
+/** Shape of system columns on every returned row (camelCase, underscore-prefixed) */
+interface SystemRow {
+	_id: string;
+	_blockHeight: number;
+	_txId: string;
+	_createdAt: string;
+}
+/** Infer the row shape for a single table definition */
+type InferTableRow<T extends SubgraphTable> = SystemRow & { [K in keyof T["columns"]] : InferColumnType<T["columns"][K]> };
+/** Comparison operators for a scalar value */
+type ComparisonFilter<T> = {
+	eq?: T
+	neq?: T
+	gt?: T
+	gte?: T
+	lt?: T
+	lte?: T
+};
+/** Where clause — each column accepts a scalar (eq) or comparison object */
+type WhereInput<TRow> = { [K in keyof TRow]? : TRow[K] | ComparisonFilter<TRow[K]> };
+/**
+* No-prefix aliases for system columns accepted in where/orderBy inputs.
+* Both `_blockHeight` and `blockHeight` are valid — serializer handles mapping.
+*/
+type SystemWhereAliases = {
+	blockHeight?: number | ComparisonFilter<number>
+	txId?: string | ComparisonFilter<string>
+	createdAt?: string | ComparisonFilter<string>
+	id?: string | ComparisonFilter<string>
+};
+type SystemOrderByAliases = {
+	blockHeight?: "asc" | "desc"
+	txId?: "asc" | "desc"
+	createdAt?: "asc" | "desc"
+	id?: "asc" | "desc"
+};
+interface FindManyOptions<TRow> {
+	where?: WhereInput<TRow> & SystemWhereAliases;
+	orderBy?: { [K in keyof TRow]? : "asc" | "desc" } & SystemOrderByAliases;
+	limit?: number;
+	offset?: number;
+	fields?: (keyof TRow & string)[];
+}
+interface SubgraphTableClient<TRow> {
+	findMany(options?: FindManyOptions<TRow>): Promise<TRow[]>;
+	count(where?: WhereInput<TRow> & SystemWhereAliases): Promise<number>;
+}
+/** Infer a typed client object from a subgraph definition shape */
+type InferSubgraphClient<T> = T extends {
+	schema: infer S
+} ? { [K in keyof S] : S[K] extends SubgraphTable ? SubgraphTableClient<InferTableRow<S[K]>> : never } : never;
+export { validateSubgraphDefinition, sourceKey, reindexSubgraph, pgSchemaName, generateSubgraphSQL, diffSchema, deploySchema, defineSubgraph, WhereInput, TableDiff, SystemRow, SubgraphTableClient, SubgraphTable, SubgraphSource, SubgraphSchema, SubgraphHandler, SubgraphDefinition, SubgraphContext, SubgraphColumn, ReindexOptions, InferTableRow, InferSubgraphClient, InferColumnType, GeneratedSQL, FindManyOptions, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff };