@secondlayer/subgraphs 7.0.1 → 7.0.2

package/dist/index.d.ts

@@ -77,13 +77,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",
@@ -669,21 +680,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 */
@@ -911,8 +954,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 +979,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 +995,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 +1021,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;
@@ -1029,8 +1078,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 +1115,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,8 +1126,10 @@ 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;
 interface PinInput {
@@ -1109,9 +1165,10 @@ 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>;
 interface GeneratedSQL {
@@ -1135,15 +1192,23 @@ 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;
 interface DrizzleGenOptions {
 	schemaName?: string;
 }
+/** Generates Drizzle table definitions for a subgraph's tables. */
 declare function generateDrizzleSchema(def: SubgraphDefinition, opts?: DrizzleGenOptions): string;
 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,
@@ -1166,6 +1231,12 @@ 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";
@@ -1209,10 +1280,11 @@ 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;
@@ -1241,11 +1313,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 +1348,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 +1369,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.2",
   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.1",
+    "@secondlayer/stacks": "^6.2.1",
+    "@secondlayer/verify": "^0.5.3",
     esbuild: "^0.28.2",
     kysely: "0.28.17",
     zod: "^4.3.6"
@@ -2948,5 +2949,5 @@ export {
   validateSubgraphDefinition
 };
 
-//# debugId=576C0AFC5A24E02A64756E2164756E21
+//# debugId=C76A905109964E7E64756E2164756E21
 //# sourceMappingURL=index.js.map