@secondlayer/subgraphs 6.3.6 → 6.5.0

package/dist/testing/index.d.ts

@@ -15,7 +15,7 @@ import { AbiContract as AbiContract3, ExtractFunctionArgs as ExtractFunctionArgs
 */
 type ChainReadCacheMode = "per-block" | "contract-constant";
 type ChainReadOptions = {
-	cache?: ChainReadCacheMode
+	cache?: ChainReadCacheMode;
 };
 /**
 * `ChainReadClient` with the ABI generic erased. Structurally cheap, so the
@@ -24,7 +24,7 @@ type ChainReadOptions = {
 */
 interface ErasedChainReadClient {
 	contract(contractId: string, abi: unknown, options?: ChainReadOptions): {
-		read: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>
+		read: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>;
 	};
 }
 import { AbiContract as AbiContract2 } from "@secondlayer/stacks/clarity";
@@ -87,7 +87,7 @@ interface StxLockFilter {
 * as-of each processed block. Lets a source index "all SIP-010 tokens" etc.
 */
 type TraitScope = {
-	trait?: string
+	trait?: string;
 };
 /**
 * Scope a source to a DYNAMIC address set discovered from another source's
@@ -127,10 +127,10 @@ type TraitScope = {
 interface FactoryScope {
 	factory?: {
 		/** Source name whose events reveal the addresses. */
-		from: string
+		from: string;
 		/** Dotted path to the address on that source's payload
 		*  (e.g. `"data.pool"`, `"contractId"`, `"data.token.id"`). */
-		field: string
+		field: string;
 	};
 }
 /** FT event filters */
@@ -203,12 +203,12 @@ interface ContractCallEvent {
 	resultHex: string | null;
 	/** Transaction metadata. */
 	tx: {
-		txId: string
-		sender: string
-		type: string
-		status: string
-		contractId: string | null
-		functionName: string | null
+		txId: string;
+		sender: string;
+		type: string;
+		status: string;
+		contractId: string | null;
+		functionName: string | null;
 	};
 }
 /** Contract event filters */
@@ -277,12 +277,12 @@ interface MapWriteFilter extends TraitScope, FactoryScope {
 * - `{ list: F }` — a list of `F`.
 */
 type PrintField = ColumnType | {
-	type: PrintField
-	optional: true
+	type: PrintField;
+	optional: true;
 } | {
-	tuple: Record<string, PrintField>
+	tuple: Record<string, PrintField>;
 } | {
-	list: PrintField
+	list: PrintField;
 };
 /**
 * Per-topic field schema for a print_event source. When declared, the handler's
@@ -294,34 +294,34 @@ type PrintField = ColumnType | {
 */
 type PrintEventPrints = Record<string, Record<string, PrintField>>;
 type PrintEventFields = FactoryScope & {
-	type: "print_event"
-	topic?: string
+	type: "print_event";
+	topic?: string;
 };
 /**
 * Pinned to one or more contract ids with no trait — `prints` is required so
 * `event.data` is typed and empty-table handlers cannot typecheck.
 */
 type PinnedPrintEventFilter = PrintEventFields & {
-	contractId: string | readonly string[]
-	trait?: undefined
-	prints: PrintEventPrints
+	contractId: string | readonly string[];
+	trait?: undefined;
+	prints: PrintEventPrints;
 };
 /**
 * Trait-scoped print source (optionally narrowed by contractId). No single
 * schema — `prints` stays optional.
 */
 type TraitPrintEventFilter = PrintEventFields & {
-	contractId?: string | readonly string[]
-	trait: string
-	prints?: PrintEventPrints
+	contractId?: string | readonly string[];
+	trait: string;
+	prints?: PrintEventPrints;
 };
 /**
 * Unpinned / factory-only print source (no contractId). `prints` optional.
 */
 type UnpinnedPrintEventFilter = PrintEventFields & {
-	contractId?: undefined
-	trait?: string
-	prints?: PrintEventPrints
+	contractId?: undefined;
+	trait?: string;
+	prints?: PrintEventPrints;
 };
 /**
 * Print-event filter. Pinned sources (contractId set, no trait) require
@@ -354,26 +354,26 @@ interface SystemRow {
 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
+	eq?: T;
+	neq?: T;
+	gt?: T;
+	gte?: T;
+	lt?: T;
+	lte?: T;
 	/** Match any value in the set. */
-	in?: T[]
+	in?: T[];
 	/** Match none of the values in the set. */
-	notIn?: T[]
+	notIn?: T[];
 	/** SQL ILIKE pattern (case-insensitive); `%`/`_` wildcards. Strings only. */
-	like?: string
+	like?: string;
 };
 /** Where clause — each column accepts a scalar (eq) or comparison object */
 type WhereInput<TRow> = { [K in keyof TRow]? : TRow[K] | ComparisonFilter<TRow[K]> };
 /** A column is optional on insert when it's nullable or has a SQL default. */
 type IsOptionalColumn<C> = C extends {
-	nullable: true
+	nullable: true;
 } ? true : C extends {
-	default: string | number | boolean
+	default: string | number | boolean;
 } ? true : false;
 /**
 * Like `InferColumnType` but for WRITE inputs: numeric (`uint`/`int`) columns
@@ -404,12 +404,12 @@ type RowWhere<
 */
 interface TypedSubgraphContext<S extends SubgraphSchema> {
 	block: {
-		height: number
-		hash: string
-		timestamp: number
-		burnBlockHeight: number
+		height: number;
+		hash: string;
+		timestamp: number;
+		burnBlockHeight: number;
 		/** Nakamoto StacksBlockId, when the block row carries one. */
-		indexBlockHash?: string | null
+		indexBlockHash?: string | null;
 	};
 	tx: TxMeta;
 	/**
@@ -521,10 +521,10 @@ interface ContractDeployPayload {
 * present for back-compat. Without an `abi`, the payload is {@link ContractCallEvent}.
 */
 type ContractCallPayload<F> = F extends {
-	abi: infer A extends AbiContract3
-	functionName: infer N extends string
+	abi: infer A extends AbiContract3;
+	functionName: infer N extends string;
 } ? N extends ExtractFunctionNames<A> ? ContractCallEvent & {
-	input: ExtractFunctionArgs2<A, N>
+	input: ExtractFunctionArgs2<A, N>;
 } : ContractCallEvent : ContractCallEvent;
 interface NestedContractCallPayload {
 	contractId: string;
@@ -568,24 +568,24 @@ interface MapDeletePayload {
 * per topic; otherwise it falls back to the untyped {@link PrintEventPayload}.
 */
 type PrintEventFor<F> = F extends {
-	prints: infer P extends Record<string, Record<string, PrintField>>
+	prints: infer P extends Record<string, Record<string, PrintField>>;
 } ? { [K in keyof P] : {
-	contractId: string
-	topic: K
-	data: PrintDataOf<P[K]>
-	tx: TxMeta
+	contractId: string;
+	topic: K;
+	data: PrintDataOf<P[K]>;
+	tx: TxMeta;
 } }[keyof P] : PrintEventPayload;
 /** TS type of one declared print field (nested tuples and lists included). */
 type PrintFieldToTS<F> = F extends ColumnType ? ColumnToTS<F> : F extends {
-	type: infer Inner
-	optional: true
+	type: infer Inner;
+	optional: true;
 } ? PrintFieldToTS<Inner> : F extends {
-	tuple: infer T extends Record<string, PrintField>
+	tuple: infer T extends Record<string, PrintField>;
 } ? PrintDataOf<T> : F extends {
-	list: infer Item
+	list: infer Item;
 } ? PrintFieldToTS<Item>[] : unknown;
 type OptionalFieldKeys<T> = { [K in keyof T] : T[K] extends {
-	optional: true
+	optional: true;
 } ? K : never }[keyof T];
 /** Collapse an intersection into one object literal, so hovering `event.data`
 *  shows the fields rather than `A & B`. */
@@ -598,37 +598,37 @@ type Flatten<T> = { [K in keyof T] : T[K] } & {};
 type PrintDataOf<T extends Record<string, PrintField>> = Flatten<{ [K in Exclude<keyof T, OptionalFieldKeys<T>>] : PrintFieldToTS<T[K]> } & { [K in OptionalFieldKeys<T>]? : PrintFieldToTS<T[K]> }>;
 /** The event payload a handler receives for a given source filter. */
 type EventForFilter<F extends SubgraphFilter> = F extends {
-	type: "print_event"
+	type: "print_event";
 } ? PrintEventFor<F> : F extends {
-	type: "ft_transfer"
+	type: "ft_transfer";
 } ? FtTransferPayload : F extends {
-	type: "ft_mint"
+	type: "ft_mint";
 } ? FtMintPayload : F extends {
-	type: "ft_burn"
+	type: "ft_burn";
 } ? FtBurnPayload : F extends {
-	type: "nft_transfer"
+	type: "nft_transfer";
 } ? NftTransferPayload : F extends {
-	type: "nft_mint"
+	type: "nft_mint";
 } ? NftMintPayload : F extends {
-	type: "nft_burn"
+	type: "nft_burn";
 } ? NftBurnPayload : F extends {
-	type: "stx_transfer"
+	type: "stx_transfer";
 } ? StxTransferPayload : F extends {
-	type: "stx_mint"
+	type: "stx_mint";
 } ? StxMintPayload : F extends {
-	type: "stx_burn"
+	type: "stx_burn";
 } ? StxBurnPayload : F extends {
-	type: "stx_lock"
+	type: "stx_lock";
 } ? StxLockPayload : F extends {
-	type: "contract_call"
+	type: "contract_call";
 } ? ContractCallPayload<F> : F extends {
-	type: "contract_deploy"
+	type: "contract_deploy";
 } ? ContractDeployPayload : F extends {
-	type: "nested_contract_call"
+	type: "nested_contract_call";
 } ? NestedContractCallPayload : F extends {
-	type: "var_set"
+	type: "var_set";
 } ? VarSetPayload : F extends {
-	type: infer T extends "map_set" | "map_insert" | "map_delete"
+	type: infer T extends "map_set" | "map_insert" | "map_delete";
 } ? T extends "map_delete" ? MapDeletePayload : MapWritePayload : never;
 interface BlockMeta {
 	height: number;
@@ -658,26 +658,26 @@ interface MatchedTx {
 	sourceName: string;
 }
 type TxRecord = {
-	tx_id: string
-	type: string
-	sender: string
-	status: string
+	tx_id: string;
+	type: string;
+	sender: string;
+	status: string;
 	/** Position within the block — the runner sorts dispatch into chain order. */
-	tx_index?: number
-	contract_id?: string | null
-	function_name?: string | null
-	function_args?: unknown | null
-	raw_result?: string | null
+	tx_index?: number;
+	contract_id?: string | null;
+	function_name?: string | null;
+	function_args?: unknown | null;
+	raw_result?: string | null;
 };
 type EventRecord = {
-	id: string
-	tx_id: string
-	type: string
+	id: string;
+	tx_id: string;
+	type: string;
 	/** Classic `event_index`, or `ordinal` when `clock === "vm"`. */
-	event_index: number
-	data: unknown
+	event_index: number;
+	data: unknown;
 	/** Set on opt-in `vm_events` rows. Two clocks never sort or dedupe together. */
-	clock?: "vm"
+	clock?: "vm";
 };
 /**
 * Build a typed event payload based on the source filter type.
@@ -699,9 +699,9 @@ interface TestSubgraphContext<S extends SubgraphSchema> extends Omit<TypedSubgra
 	setTx(tx: Partial<TxMeta2>): void;
 	/** Insert ops queued since `opsCheckpoint()`, for preview IN/OUT traces. */
 	pendingInsertsSince(checkpoint: number): Array<{
-		table: string
-		keys: string[]
-		row: Record<string, unknown>
+		table: string;
+		keys: string[];
+		row: Record<string, unknown>;
 	}>;
 	/** Length of the pending-ops queue (same as runtime `opsCheckpoint`). */
 	opsCheckpoint(): number;
@@ -716,11 +716,11 @@ interface TestSubgraphContext<S extends SubgraphSchema> extends Omit<TypedSubgra
 * ```
 */
 declare function createTestContext<const S extends SubgraphSchema>(schema: S, options?: {
-	block?: Partial<BlockMeta>
-	tx?: Partial<TxMeta2>
+	block?: Partial<BlockMeta>;
+	tx?: Partial<TxMeta2>;
 	/** Stubbed `ctx.client.readOnly` results, keyed
 	*  `"<contractId>.<function-name>"`. */
-	reads?: Record<string, unknown>
+	reads?: Record<string, unknown>;
 }): TestSubgraphContext<S>;
 /**
 * Build a handler-shaped event payload for a source, typed by that source's
@@ -735,7 +735,7 @@ declare function createTestContext<const S extends SubgraphSchema>(schema: S, op
 * ```
 */
 declare function buildEvent<const F extends SubgraphFilter>(source: F, payload: Record<string, unknown>, options?: {
-	tx?: Partial<TxMeta2>
+	tx?: Partial<TxMeta2>;
 }): EventForFilter<F>;
 /**
 * Shared subgraph test run — payload map + in-memory handlers + fail-closed
@@ -785,8 +785,8 @@ interface EventTrace {
 	inKeys: string[];
 	/** Tables written by this event; empty when the mapping wrote nothing. */
 	outs: Array<{
-		table: string
-		keys: string[]
+		table: string;
+		keys: string[];
 	}>;
 }
 interface SubgraphTestResult {
@@ -795,13 +795,13 @@ interface SubgraphTestResult {
 	matched: number;
 	written: number;
 	tables: Array<{
-		name: string
-		rows: number
-		sampleRow?: Record<string, unknown>
+		name: string;
+		rows: number;
+		sampleRow?: Record<string, unknown>;
 	}>;
 	firstEvent?: {
-		source: string
-		data?: unknown
+		source: string;
+		data?: unknown;
 	};
 	hint?: string;
 	/** Present when `trace: true`. */
@@ -819,7 +819,7 @@ interface RunSubgraphTestInput {
 }
 /** Map an Index event row onto the payload shape a handler expects. */
 declare function toHandlerPayload(_filter: {
-	type: string
+	type: string;
 } | undefined, row: IndexEventRow): Record<string, unknown>;
 /** Map an Index contract-call row onto the ContractCallEvent handler shape. */
 declare function toContractCallPayload(row: IndexContractCallRow): Record<string, unknown>;
@@ -831,8 +831,8 @@ declare function runSubgraphTest(input: RunSubgraphTestInput): Promise<SubgraphT
 interface ProbeHandlersDef {
 	schema: SubgraphSchema;
 	sources: Record<string, {
-		type: string
-		[key: string]: unknown
+		type: string;
+		[key: string]: unknown;
 	}>;
 	handlers: Record<string, unknown>;
 }
@@ -848,7 +848,7 @@ interface ProbeHandlersResult {
 * EMPTY_MAPPING before DDL apply.
 */
 declare function probeHandlers(def: ProbeHandlersDef, samples: Array<{
-	source: string
-	event: Record<string, unknown>
+	source: string;
+	event: Record<string, unknown>;
 }>): Promise<ProbeHandlersResult>;
 export { BlockMeta, EventTrace, IndexContractCallRow, IndexEventRow, IndexTestRow, ProbeHandlersDef, ProbeHandlersResult, RunSubgraphTestInput, SubgraphTestResult, SubgraphTestSource, TestSubgraphContext, TxMeta2 as TxMeta, buildEvent, buildEventPayload, createTestContext, probeHandlers, runSubgraphTest, toContractCallPayload, toHandlerPayload };