@secondlayer/subgraphs 7.0.1 → 7.0.3

package/dist/index.d.ts

@@ -17,6 +17,7 @@ import { AbiContract, ExtractFunctionArgs, ExtractFunctionOutput, ExtractReadOnl
 *   first answer forever, so it is opt-in and never inferred.
 */
 type ChainReadCacheMode = "per-block" | "contract-constant";
+/** Options for a contract read, such as cache mode. */
 type ChainReadOptions = {
 	cache?: ChainReadCacheMode;
 };
@@ -77,13 +78,24 @@ type ChainReadMethods<C extends AbiContract> = { [N in ExtractReadOnlyFunctions<
 * one and handlers get full inference.
 */
 interface ErasedChainReadClient {
+	/**
+	* Reads a contract's read-only functions at the block being processed.
+	*
+	* Results are untyped here. Call it through `readContractAt` to get typed
+	* results from the contract's ABI.
+	*/
 	contract(contractId: string, abi: unknown, options?: ChainReadOptions): {
 		read: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>;
 	};
 }
 /**
-* Typed read methods for one contract, from a handler.
+* Reads a contract's read-only functions from a handler, with typed results.
 *
+* Pass `ctx`, the contract id and its ABI. Every call is pinned to the block
+* being processed. Set `options.cache` to `"contract-constant"` to fetch a
+* value once per contract instead of once per block.
+*
+* @example
 * ```ts
 * const token = readContractAt(ctx, contractId, SIP010_ABI, {
 *   cache: "contract-constant",
@@ -126,7 +138,7 @@ interface SubgraphTable {
 	/** Unique key constraints (each entry is an array of column names). Required for upsert. */
 	uniqueKeys?: readonly (readonly string[])[];
 }
-/** Subgraph schema — maps table names to table definitions */
+/** Maps table names to table definitions. */
 type SubgraphSchema = Record<string, SubgraphTable>;
 /** STX event filters */
 interface StxTransferFilter {
@@ -398,7 +410,7 @@ type UnpinnedPrintEventFilter = PrintEventFields & {
 * `prints`; trait and unpinned sources may omit it.
 */
 type PrintEventFilter = PinnedPrintEventFilter | TraitPrintEventFilter | UnpinnedPrintEventFilter;
-/** All subgraph filter types — discriminated on `type` */
+/** A subgraph filter, discriminated on `type`. */
 type SubgraphFilter = StxTransferFilter | StxMintFilter | StxBurnFilter | StxLockFilter | FtTransferFilter | FtMintFilter | FtBurnFilter | NftTransferFilter | NftMintFilter | NftBurnFilter | ContractCallFilter | ContractDeployFilter | PrintEventFilter | NestedContractCallFilter | VarSetFilter | MapWriteFilter;
 /** Transaction metadata available in handlers */
 interface TxMeta {
@@ -669,21 +681,53 @@ interface TypedSubgraphContext<S extends SubgraphSchema> {
 	* `readContractAt(ctx, id, abi)` for full ABI typing at the call site.
 	*/
 	client: ErasedChainReadClient;
+	/**
+	* Queues a new row for a table.
+	*
+	* Writes are batched and applied together when the block commits.
+	* `_block_height` and `_tx_id` are filled in for you.
+	*/
 	insert<T extends TableName<S>>(table: T, row: WriteRow<S[T]>): void;
+	/**
+	* Queues an update to the rows matching `where`.
+	*
+	* `set` holds only the columns to change.
+	*/
 	update<T extends TableName<S>>(table: T, where: RowWhere<S, T>, set: Partial<WriteRow<S[T]>>): void;
+	/**
+	* Inserts a row, or updates the one with the same key.
+	*
+	* `key` should match a `uniqueKeys` constraint of the table. Without one the
+	* write falls back to a lookup first and logs a warning.
+	*/
 	upsert<
 		T extends TableName<S>,
 		K extends Partial<WriteRow<S[T]>>
 	>(table: T, key: K, row: Omit<WriteRow<S[T]>, keyof K> & Partial<WriteRow<S[T]>>): void;
+	/** Queues deletion of the rows matching `where`. */
 	delete<T extends TableName<S>>(table: T, where: RowWhere<S, T>): void;
 	/**
-	* Atomic accumulator — `INSERT … ON CONFLICT (key) DO UPDATE SET col =
-	* COALESCE(col,0) + delta`. Deltas commute, so it's the reorg-safe primitive
-	* for running totals (per-cycle aggregates, balances). Requires a `uniqueKeys`
-	* constraint matching `key`; deltas may be `number` or `bigint`.
+	* Adds signed deltas to a counter row, creating it if missing.
+	*
+	* It compiles to `INSERT … ON CONFLICT (key) DO UPDATE SET col =
+	* COALESCE(col,0) + delta`. Deltas commute, so it is the reorg-safe way to
+	* keep running totals such as per-cycle aggregates and balances. It needs a
+	* `uniqueKeys` constraint matching `key`, and deltas may be `number` or
+	* `bigint`.
 	*/
 	increment<T extends TableName<S>>(table: T, key: Partial<WriteRow<S[T]>>, deltas: Partial<Record<ColumnName<S, T>, bigint | number>>): void;
+	/**
+	* Returns the first row matching `where`, or `null`.
+	*
+	* Reads see the writes queued earlier in the same block, and rows come back
+	* in insertion order.
+	*/
 	findOne<T extends TableName<S>>(table: T, where: RowWhere<S, T>): Promise<InferTableRow<S[T]> | null>;
+	/**
+	* Returns every row matching `where`, in insertion order.
+	*
+	* Reads see the writes queued earlier in the same block.
+	*/
 	findMany<T extends TableName<S>>(table: T, where: RowWhere<S, T>): Promise<InferTableRow<S[T]>[]>;
 }
 /** Infer a typed client object from a subgraph definition shape */
@@ -900,8 +944,11 @@ type TypedHandlers<
 	Sources extends Record<string, SubgraphFilter>,
 	S extends SubgraphSchema
 > = { [K in keyof Sources]-? : HandlerFn<Sources[K], S> };
-/** Subgraph definition with `sources`/`schema` literals preserved for typed
-* handlers and downstream query-client inference (`getSubgraph`). */
+/**
+* A subgraph definition that keeps `sources` and `schema` literals typed.
+*
+* Preserved for typed handlers and downstream query-client inference (`getSubgraph`).
+*/
 type TypedSubgraphDefinition<
 	Sources extends Record<string, SubgraphFilter>,
 	S extends SubgraphSchema
@@ -911,8 +958,10 @@ type TypedSubgraphDefinition<
 	handlers: TypedHandlers<Sources, S>;
 };
 /**
-* Identity function that preserves `sources` and `schema` literal types so
-* handlers are typed per source and the schema drives query-client inference.
+* Declares a subgraph and keeps its source and schema literal types.
+*
+* Handlers are typed per source, and the schema drives query-client inference.
+* It returns its argument unchanged.
 *
 * @example
 * ```ts
@@ -934,9 +983,14 @@ declare function defineSubgraph<
 	const S extends SubgraphSchema
 >(def: TypedSubgraphDefinition<Sources, S>): TypedSubgraphDefinition<Sources, S>;
 /**
-* Identity helper that preserves a schema literal's exact types so it can be
-* HOISTED out of the `defineSubgraph()` call and reused:
+* Declares a schema you can hoist out of `defineSubgraph()` and reuse.
+*
+* It keeps the schema's literal types, so table names and row columns stay
+* checked in helpers typed `TypedSubgraphContext<typeof schema>`. `as const`
+* alone does not work: it produces `readonly` arrays that a mutable
+* `uniqueKeys` rejects, and a bare literal widens `type` to `string`.
 *
+* @example
 * ```ts
 * const schema = defineSchema({
 *   balances: {
@@ -945,19 +999,14 @@ declare function defineSubgraph<
 *   },
 * });
 *
-* // An extracted helper keeps the full typed surface — table names and row
-* // columns are still checked:
+* // An extracted helper keeps the full typed surface: table names and row
+* // columns are still checked.
 * function credit(ctx: TypedSubgraphContext<typeof schema>, holder: string) {
 *   ctx.increment("balances", { holder }, { amount: 1n });
 * }
 *
 * defineSubgraph({ name: "balances", schema, sources, handlers });
 * ```
-*
-* `as const` alone does not work here (it produces `readonly` arrays that a
-* mutable `uniqueKeys` rejected) and a bare literal widens `type` to `string`.
-* That gap is why the shipped starter typed its helper `ctx: any` — and in
-* doing so modelled a non-commutative read-modify-write the docs warn against.
 */
 declare function defineSchema<const S extends SubgraphSchema>(schema: S): S;
 /**
@@ -976,14 +1025,18 @@ type InferContext<D> = D extends {
 	schema: infer S extends SubgraphSchema;
 } ? TypedSubgraphContext<S> : never;
 /**
-* Validates a subgraph definition, returning the parsed result or throwing on failure.
+* Validates a subgraph definition and returns the parsed result.
+*
+* It throws when the definition is invalid.
 */
 declare function validateSubgraphDefinition(def: unknown): SubgraphDefinition;
 /**
-* Per-source-type field vocabulary, DERIVED from
-* {@link SubgraphFilterSchema}. Agent-facing surfaces (the MCP filters
-* reference) used to hand-maintain a parallel copy of this list; deriving it
-* means adding a field to a filter can never leave the documentation behind.
+* Lists the fields each source filter type accepts.
+*
+* The list is derived from {@link SubgraphFilterSchema}. Agent-facing surfaces
+* such as the MCP filters reference used to keep a parallel copy by hand;
+* deriving it means adding a field to a filter can never leave the
+* documentation behind.
 */
 declare function filterFieldsByType(): Array<{
 	type: string;
@@ -1021,6 +1074,7 @@ interface InferredPrintField {
 	/** Only when optional observed: share of present samples that were some */
 	optional_some_rate?: number;
 }
+/** The fields seen in one `print` topic, with counts and heights. */
 interface InferredTopicSchema {
 	topic: string;
 	count: number;
@@ -1029,8 +1083,12 @@ interface InferredTopicSchema {
 	non_tuple: boolean;
 	fields: InferredPrintField[];
 }
-/** Recursively camelize object keys with the print-payload helper (not ABI
-*  `toCamelCase` — that one strips `-STX` and prefixes leading digits). */
+/**
+* Camelizes object keys recursively, the way print payloads are.
+*
+* It uses the print-payload helper, not ABI `toCamelCase`, which strips `-STX`
+* and prefixes leading digits.
+*/
 declare function camelizeKeys(obj: unknown): unknown;
 /**
 * Infers per-topic field schemas from sampled print events. Counts and
@@ -1062,6 +1120,7 @@ interface HandlerFinding {
 	/** 1-based. */
 	column: number;
 }
+/** Formats a handler finding as `file:line:column name: reason`. */
 declare function formatFinding(f: HandlerFinding): string;
 /**
 * Derive how far a subgraph's rows can be checked. Level = the highest any
@@ -1072,10 +1131,13 @@ declare function formatFinding(f: HandlerFinding): string;
 */
 declare function deriveVerification(def: Pick<SubgraphDefinition, "sources" | "backfillMode">, findings?: readonly HandlerFinding[]): SubgraphVerification;
 /**
-* True when the deploy must be refused: the sources are provable (`state`), so
-* the determinism contract is enforced, and the scan broke it.
+* Tells whether a deploy must be refused for breaking determinism.
+*
+* It is refused when the sources are provable (`state`), so the determinism
+* contract is enforced, and the scan broke it.
 */
 declare function isDeterminismViolation(v: SubgraphVerification): boolean;
+/** What a pin is computed from: schema hash, handler code, network. */
 interface PinInput {
 	/** Existing `schema_hash` (name + schema + sources). */
 	schemaHash: string;
@@ -1109,11 +1171,13 @@ declare class HandlerReadError extends Error {
 	name: string;
 }
 /**
-* Evaluate a bundled handler (ESM, as stored in `handler_code`) inside a
-* fresh deterministic realm and return its definition with every handler
-* wrapped to receive the {@link deterministicContext} facade.
+* Loads a bundled handler into a fresh deterministic realm.
+*
+* The bundle is ESM, as stored in `handler_code`. The returned definition has
+* every handler wrapped to receive the {@link deterministicContext} facade.
 */
 declare function loadDeterministicDefinition(handlerCode: string): Promise<SubgraphDefinition>;
+/** The SQL statements for a subgraph's tables and their hash. */
 interface GeneratedSQL {
 	statements: string[];
 	hash: string;
@@ -1124,6 +1188,7 @@ interface GeneratedSQL {
 * each with auto-columns and indexes.
 */
 declare function generateSubgraphSQL(def: SubgraphDefinition, schemaNameOverride?: string): GeneratedSQL;
+/** Options for generating Prisma models. */
 interface PrismaGenOptions {
 	/** Postgres schema the tables live in (account-scoped). */
 	schemaName?: string;
@@ -1135,15 +1200,25 @@ interface PrismaGenOptions {
 	*/
 	modelsOnly?: boolean;
 }
+/**
+* Generates a Prisma schema for a subgraph's tables.
+*
+* Set `modelsOnly` to emit just the `model` blocks, to compose with your own
+* schema.
+*/
 declare function generatePrismaSchema(def: SubgraphDefinition, opts?: PrismaGenOptions): string;
+/** Options for generating Drizzle table definitions. */
 interface DrizzleGenOptions {
 	schemaName?: string;
 }
+/** Generates Drizzle table definitions for a subgraph's tables. */
 declare function generateDrizzleSchema(def: SubgraphDefinition, opts?: DrizzleGenOptions): string;
+/** Options for generating Kysely table interfaces. */
 interface KyselyGenOptions {
 	/** Postgres schema the tables live in (account-scoped). */
 	schemaName?: string;
 }
+/** Generates Kysely table interfaces for a subgraph's tables. */
 declare function generateKyselySchema(def: SubgraphDefinition, opts?: KyselyGenOptions): string;
 /**
 * Emit a portable, typed schema for the public Index read domain (blocks,
@@ -1157,7 +1232,9 @@ declare function generateKyselySchema(def: SubgraphDefinition, opts?: KyselyGenO
 * physical PK is a synthetic id excluded from the read contract (chain_reorgs) have
 * no read-set key and are omitted from Prisma output (other targets still emit them).
 */
+/** A portable, typed schema target for the public Index read domain. */
 type IndexCodegenTarget = "prisma" | "kysely" | "drizzle" | "json-schema";
+/** Options for generating the Index schema: tables, schema name. */
 interface IndexCodegenOptions {
 	/** Restrict output to these Index tables (default: all). */
 	tables?: string[];
@@ -1166,11 +1243,18 @@ interface IndexCodegenOptions {
 	/** Prisma only: datasource url env var (default DATABASE_URL). */
 	datasourceEnv?: string;
 }
+/**
+* Generates a typed schema for Index tables.
+*
+* `target` picks Prisma, Kysely, Drizzle or JSON Schema. Use `tables` to limit
+* the output. Prisma omits tables with no read-set key.
+*/
 declare function generateIndexSchema(target: IndexCodegenTarget, opts?: IndexCodegenOptions): string;
 import { pgSchemaName } from "@secondlayer/shared/db/queries/subgraphs";
 import { Database as Database2 } from "@secondlayer/shared/db";
 import { Kysely as Kysely2 } from "kysely";
 type AnyDb = Kysely2<Database2>;
+/** Tables added, removed, or changed between two schemas. */
 interface TableDiff {
 	/** Tables added to the schema */
 	addedTables: string[];
@@ -1209,15 +1293,17 @@ interface ConstraintDiff {
 */
 declare function diffSchema(existing: SubgraphSchema, incoming: SubgraphSchema): TableDiff;
 /**
-* Returns true if the diff contains any breaking changes
-* (removed tables, removed columns, changed column types, or removed
-* uniqueKeys — handler upserts `ON CONFLICT` against those).
-* Index-flag and composite-index changes are never breaking.
+* Tells whether a schema diff is breaking, with the reasons.
+*
+* Breaking means removed tables, removed columns, changed column types or
+* removed `uniqueKeys`, which handler upserts conflict on. Index-flag and
+* composite-index changes are never breaking.
 */
 declare function hasBreakingChanges(diff: TableDiff): {
 	breaking: boolean;
 	reasons: string[];
 };
+/** The tables and columns a deploy adds, removes, or breaks. */
 interface DeployDiff {
 	addedTables: string[];
 	removedTables: string[];
@@ -1228,6 +1314,7 @@ interface DeployDiff {
 	/** uniqueKeys added in place via ALTER TABLE … ADD CONSTRAINT. */
 	addedUniqueKeys?: Record<string, string[][]>;
 }
+/** The schema name and SQL a deploy will run. */
 interface DeployPlan {
 	schemaName: string;
 	/** `DROP SCHEMA … CASCADE` a destructive rebuild would run first. */
@@ -1241,11 +1328,12 @@ interface DeployPlan {
 */
 declare function renderDeployPlan(def: SubgraphDefinition, schemaName?: string): DeployPlan;
 /**
-* Deploy a subgraph schema to the database.
-* - New subgraph → CREATE SCHEMA + tables + register
-* - Same hash → no-op (handler path updated)
-* - Additive change → ALTER TABLE ADD COLUMN / CREATE TABLE for new tables
-* - Breaking change → auto-reindex (drop + recreate)
+* Deploys a subgraph schema to the database.
+*
+* A new subgraph gets its schema and tables created and registered. The same
+* schema hash only updates the handler path. An additive change adds columns
+* and tables in place, and a breaking change reindexes by dropping and
+* recreating the tables.
 */
 declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: string, opts?: {
 	forceReindex?: boolean;
@@ -1275,14 +1363,20 @@ type SparseProbeTarget = {
 	eventType: string;
 	contractId?: string;
 };
-/** Sparse scanning is sound only when EVERY source is an event-type filter —
-*  a contract_call/contract_deploy source matches transactions, which the
-*  event probe can't see. */
+/**
+* Tells whether a subgraph can skip blocks without its events.
+*
+* Sparse scanning is sound only when every source is an event-type filter. A
+* `contract_call` or `contract_deploy` source matches transactions, which the
+* event probe cannot see.
+*/
 declare function canSparseScan(subgraph: SubgraphDefinition): boolean;
 /**
-* The (decoded event type, contract scope) pairs a subgraph's filters can
-* match. One function feeds BOTH the sparse probe and the event walks, so a
-* new contract-pinning filter field is added here once.
+* Lists the event types and contract scopes a subgraph's filters match.
+*
+* Each target is a decoded event type with an optional contract scope. One
+* function feeds both the sparse probe and the event walks, so a new
+* contract-pinning filter field is added here once.
 *
 * Per event type: if ANY filter for it is unscoped, a single unscoped target
 * covers everything (today's behavior); otherwise one target per distinct
@@ -1290,12 +1384,13 @@ declare function canSparseScan(subgraph: SubgraphDefinition): boolean;
 */
 declare function sparseProbeTargets(subgraph: SubgraphDefinition): SparseProbeTarget[];
 /**
-* streams-index eligibility: every source must be a known event-type or
-* contract_call/contract_deploy filter (no array-style sources, which leak the
-* unreconstructable `_eventId`). Trait scope IS allowed — trait resolution
-* reads the contract registry on the platform DB (`targetDb`), which the
-* processor always holds, so it's source-independent. Everything else stays on
-* the DB tap.
+* Tells whether a subgraph's sources can be read from the Streams index.
+*
+* Every source must be a known event-type, `contract_call` or
+* `contract_deploy` filter, and array-style sources never qualify because they
+* leak the unreconstructable `_eventId`. Trait scope is allowed: trait
+* resolution reads the contract registry on the platform database, which the
+* processor always holds. Everything else stays on the database tap.
 */
 declare function isStreamsIndexEligible(subgraph: SubgraphDefinition): boolean;
 interface ReindexOptions {

package/dist/index.js

@@ -787,7 +787,7 @@ import { createHash } from "node:crypto";
 // package.json
 var package_default = {
   name: "@secondlayer/subgraphs",
-  version: "7.0.1",
+  version: "7.0.3",
   description: "Describe the Stacks data you want as one TypeScript file; it fills itself and survives reorgs.",
   license: "MIT",
   repository: {
@@ -843,12 +843,13 @@ var package_default = {
     dev: "bunup --watch",
     test: "bun test",
     typecheck: "tsc --noEmit",
+    openpkg: "bun scripts/sync-openpkg.ts",
     prepublishOnly: "bun run build"
   },
   dependencies: {
-    "@secondlayer/shared": "^12.0.0",
-    "@secondlayer/stacks": "^6.2.0",
-    "@secondlayer/verify": "^0.5.0",
+    "@secondlayer/shared": "^12.1.2",
+    "@secondlayer/stacks": "^6.2.2",
+    "@secondlayer/verify": "^0.5.4",
     esbuild: "^0.28.2",
     kysely: "0.28.17",
     zod: "^4.3.6"
@@ -2948,5 +2949,5 @@ export {
   validateSubgraphDefinition
 };
 
-//# debugId=576C0AFC5A24E02A64756E2164756E21
+//# debugId=E3F910C01BB06DA264756E2164756E21
 //# sourceMappingURL=index.js.map