@secondlayer/subgraphs 4.1.4 → 4.2.0

package/dist/src/index.d.ts

@@ -190,7 +190,12 @@ type TraitScope = {
 *
 * ```ts
 * sources: {
-*   registry: { type: "print_event", contractId: REGISTRY, topic: "pool-created" },
+*   registry: {
+*     type: "print_event",
+*     contractId: REGISTRY,
+*     topic: "pool-created",
+*     prints: { "pool-created": { pool: "principal" } },
+*   },
 *   swaps: {
 *     type: "print_event",
 *     topic: "swap",
@@ -315,6 +320,9 @@ interface ContractCallFilter extends TraitScope, FactoryScope {
 	* decoded function arguments. Dev-provided; serialized into the deployed
 	* definition and used at runtime to decode args by name. Omit to keep
 	* `event.args` as a positional `unknown[]`.
+	*
+	* Deploy validation requires `abi` whenever `functionName` is set
+	* (`normalizeAbi()` from `@secondlayer/stacks/clarity`).
 	*/
 	abi?: AbiContract2;
 }
@@ -345,29 +353,70 @@ type PrintField = ColumnType | {
 } | {
 	list: PrintField
 };
-interface PrintEventFilter extends TraitScope, FactoryScope {
-	type: "print_event";
-	/** One contract id, or a set of them (max 20). Supports `*` wildcards.
-	*  COMPOSES with `trait` — the matcher ANDs them, so the pair means
-	*  "contracts conforming to this trait, narrowed to these ids". (The Index
-	*  read API refuses the combination, but that is its query planner's
-	*  constraint, not a semantic one.) */
-	contractId?: string | readonly string[];
-	topic?: string;
-	/**
-	* Per-topic field schema. When declared, the handler's `event` is a
-	* discriminated union keyed by `topic` and `event.data` is typed per topic
-	* (e.g. `{ "completed-deposit": { amount: "uint", sender: "principal" } }`).
-	* Nested tuples, lists, and optional fields are expressible — see
-	* {@link PrintField}.
-	*
-	* Declaring `prints` also opts the source into RUNTIME validation: an
-	* event whose decoded payload does not match is skipped and logged rather
-	* than written as nulls (and the deploy-time field lint is promoted from
-	* a warning to an error).
-	*/
-	prints?: Record<string, Record<string, PrintField>>;
+/**
+* Per-topic field schema for a print_event source. When declared, the handler's
+* `event` is a discriminated union keyed by `topic` and `event.data` is typed
+* per topic. Nested tuples, lists, and optional fields — see {@link PrintField}.
+*
+* Also opts the source into RUNTIME validation: a payload that does not match
+* is skipped and logged rather than written as nulls.
+*/
+type PrintEventPrints = Record<string, Record<string, PrintField>>;
+/**
+* One column in a static identity map. Literals only — the bundler never
+* executes user code, so `{ from: "tokenX" }` is valid and `from("tokenX")`
+* is not.
+*/
+type MaterializeColumn = {
+	from: string
+} | {
+	fromTx: "sender" | "txId"
+} | {
+	fromBlock: "height" | "hash" | "timestamp"
+};
+/** Static insert from a source event — replaces a 1:1 handler. */
+interface MaterializeSpec {
+	table: string;
+	/** Keys = schema column names (snake). */
+	columns: Record<string, MaterializeColumn>;
 }
+type PrintEventFields = FactoryScope & {
+	type: "print_event"
+	topic?: string
+	/** Identity map: insert without a handler function. XOR with handlers[name]. */
+	materialize?: MaterializeSpec
+};
+/**
+* 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
+};
+/**
+* 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
+};
+/**
+* Unpinned / factory-only print source (no contractId). `prints` optional.
+*/
+type UnpinnedPrintEventFilter = PrintEventFields & {
+	contractId?: undefined
+	trait?: string
+	prints?: PrintEventPrints
+};
+/**
+* Print-event filter. Pinned sources (contractId set, no trait) require
+* `prints`; trait and unpinned sources may omit it.
+*/
+type PrintEventFilter = PinnedPrintEventFilter | TraitPrintEventFilter | UnpinnedPrintEventFilter;
 /** All subgraph filter types — discriminated on `type` */
 type SubgraphFilter = StxTransferFilter | StxMintFilter | StxBurnFilter | StxLockFilter | FtTransferFilter | FtMintFilter | FtBurnFilter | NftTransferFilter | NftMintFilter | NftBurnFilter | ContractCallFilter | ContractDeployFilter | PrintEventFilter;
 /** Transaction metadata available in handlers */
@@ -909,19 +958,25 @@ type EventForFilter<F extends SubgraphFilter> = F extends {
 } ? ContractDeployPayload : never;
 /** Union of every event payload — the `"*"` catch-all handler receives this. */
 type AnyEvent = FtTransferPayload | FtMintPayload | FtBurnPayload | NftTransferPayload | NftMintPayload | NftBurnPayload | StxTransferPayload | StxMintPayload | StxBurnPayload | StxLockPayload | PrintEventPayload | ContractCallEvent | ContractDeployPayload;
+type HandlerFn<
+	F extends SubgraphFilter,
+	S extends SubgraphSchema
+> = (event: EventForFilter<F>, ctx: TypedSubgraphContext<S>) => void | Promise<void>;
+type SourceHasMaterialize<F> = F extends {
+	materialize: MaterializeSpec
+} ? true : false;
 /**
 * Handlers keyed by source name. Each handler's `event` is typed from the
 * matching source's filter `type` (e.g. a `print_event` source → `event.topic`
 * is a `string`), and `ctx` is typed against the subgraph `schema` (table
-* names + row columns checked). The optional `"*"` catch-all receives any event.
-*
-* Handlers are optional per source (a source with no handler is skipped at
-* runtime), matching `handlers[name] ?? handlers["*"]` resolution.
+* names + row columns checked). Sources with `materialize` may omit a
+* handler; every other source key is required. Optional `"*"` catch-all
+* receives any event (validate also accepts `*` alone).
 */
 type TypedHandlers<
 	Sources extends Record<string, SubgraphFilter>,
 	S extends SubgraphSchema
-> = { [K in keyof Sources]? : (event: EventForFilter<Sources[K]>, ctx: TypedSubgraphContext<S>) => void | Promise<void> } & {
+> = { [K in keyof Sources as SourceHasMaterialize<Sources[K]> extends true ? never : K]-? : HandlerFn<Sources[K], S> } & { [K in keyof Sources as SourceHasMaterialize<Sources[K]> extends true ? K : never]? : HandlerFn<Sources[K], S> } & {
 	"*"?: (event: AnyEvent, ctx: TypedSubgraphContext<S>) => void | Promise<void>
 };
 /** Subgraph definition with `sources`/`schema` literals preserved for typed
@@ -1046,10 +1101,15 @@ interface InferredTopicSchema {
 	fields: InferredPrintField[];
 }
 /**
-* Kebab-case → camelCase using the exact runner regex, so `camel_name`
-* matches what handlers see on `e.data` (runner.ts camelizeKeys).
+* Kebab-case → camelCase for print tuple keys. Canonical: the runner uses
+* this on `event.data`, and `camel_name` in inferred print schema is the
+* same function. Distinct from ABI `toCamelCase` (`transfer-STX` stays
+* `transfer-STX` here, becomes `transferSTX` there).
 */
 declare function camelizeDataKey(str: string): string;
+/** Recursively camelize object keys with the print-payload helper (not ABI
+*  `toCamelCase` — that one strips `-STX` and prefixes leading digits). */
+declare function camelizeKeys(obj: unknown): unknown;
 /**
 * Infers per-topic field schemas from sampled print events. Counts and
 * height bounds cover ALL rows of a topic (cheap); only a bounded subset is
@@ -1208,4 +1268,4 @@ declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: s
 	/** Non-fatal caveats the caller should surface (e.g. handler grafts at tip). */
 	warnings?: string[]
 }>;
-export { validateSubgraphDefinition, validatePrintPayload, sparseProbeTargets, resumeReindex, renderDeployPlan, reindexSubgraph, readContractAt, pgSchemaName, inferPrintTopics, hasBreakingChanges, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, filterFieldsByType, diffSchema, deploySchema, defineSubgraph, defineSchema, canSparseScan, camelizeDataKey, backfillSubgraph, WriteRow, WhereInput, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TableDiff, SystemRow, SubscribeOptions, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, SparseProbeTarget, RowValue, ReindexOptions, PrismaGenOptions, PrintValidationResult, PrintSample, PrintFieldToTS, PrintField, PrintEventPayload, PrintEventFor, PrintEventFilter, PrintDataOf, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, KyselyGenOptions, InferredTopicSchema, InferredPrintField, InferTableRow, InferSubgraphClient, InferContext, InferColumnType, IndexCodegenTarget, IndexCodegenOptions, INDEX_CODEGEN_TABLES, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, FactoryScope, EventForFilter, ErasedChainReadClient, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ChainReadOptions, ChainReadMethods, ChainReadError, ChainReadClient, ChainReadCacheMode, AnyEvent, AggregateSpec, AggregateResult };
+export { validateSubgraphDefinition, validatePrintPayload, sparseProbeTargets, resumeReindex, renderDeployPlan, reindexSubgraph, readContractAt, pgSchemaName, inferPrintTopics, hasBreakingChanges, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, filterFieldsByType, diffSchema, deploySchema, defineSubgraph, defineSchema, canSparseScan, camelizeKeys, camelizeDataKey, backfillSubgraph, WriteRow, WhereInput, UnpinnedPrintEventFilter, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TraitPrintEventFilter, TableDiff, SystemRow, SubscribeOptions, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, SparseProbeTarget, RowValue, ReindexOptions, PrismaGenOptions, PrintValidationResult, PrintSample, PrintFieldToTS, PrintField, PrintEventPrints, PrintEventPayload, PrintEventFor, PrintEventFilter, PrintDataOf, PinnedPrintEventFilter, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, MaterializeSpec, MaterializeColumn, KyselyGenOptions, InferredTopicSchema, InferredPrintField, InferTableRow, InferSubgraphClient, InferContext, InferColumnType, IndexCodegenTarget, IndexCodegenOptions, INDEX_CODEGEN_TABLES, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, FactoryScope, EventForFilter, ErasedChainReadClient, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ChainReadOptions, ChainReadMethods, ChainReadError, ChainReadClient, ChainReadCacheMode, AnyEvent, AggregateSpec, AggregateResult };