@secondlayer/subgraphs 7.0.1 → 7.0.3

package/dist/testing/index.d.ts

@@ -14,6 +14,7 @@ import { AbiContract as AbiContract3, ExtractFunctionArgs as ExtractFunctionArgs
 *   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;
 };
@@ -23,6 +24,12 @@ type ChainReadOptions = {
 * 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>>;
 	};
@@ -56,7 +63,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 {
@@ -328,7 +335,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 {
@@ -419,21 +426,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]>[]>;
 }
 interface FtTransferPayload {
@@ -657,6 +696,7 @@ interface MatchedTx {
 	/** Source object key — used for handler dispatch */
 	sourceName: string;
 }
+/** A transaction as a subgraph source matcher reads it. */
 type TxRecord = {
 	tx_id: string;
 	type: string;
@@ -669,6 +709,7 @@ type TxRecord = {
 	function_args?: unknown | null;
 	raw_result?: string | null;
 };
+/** An event as a subgraph source matcher reads it. */
 type EventRecord = {
 	id: string;
 	tx_id: string;
@@ -707,8 +748,13 @@ interface TestSubgraphContext<S extends SubgraphSchema> extends Omit<TypedSubgra
 	opsCheckpoint(): number;
 }
 /**
-* Build an in-memory context for a subgraph's schema.
+* Builds an in-memory context for a subgraph's schema.
 *
+* It is the real handler context with its row store swapped for memory, so
+* reads see earlier writes. Use `ctx.rows(table)` to inspect what a handler
+* wrote.
+*
+* @example
 * ```ts
 * const ctx = createTestContext(bns.schema, { block: { height: 167_484 } });
 * await bns.handlers.bns!(buildEvent(bns.sources.bns, { … }), ctx);
@@ -723,10 +769,12 @@ declare function createTestContext<const S extends SubgraphSchema>(schema: S, op
 	reads?: Record<string, unknown>;
 }): TestSubgraphContext<S>;
 /**
-* Build a handler-shaped event payload for a source, typed by that source's
-* filter. `data` supplies the decoded, camelCased fields the runtime would
-* have produced; block/tx metadata is filled in.
+* Builds a handler-shaped event for a source, typed by that source's filter.
+*
+* `data` supplies the decoded, camelCased fields the runtime would have
+* produced. Transaction metadata is filled in.
 *
+* @example
 * ```ts
 * buildEvent(bns.sources.bns, {
 *   topic: "name-register",
@@ -789,6 +837,7 @@ interface EventTrace {
 		keys: string[];
 	}>;
 }
+/** The outcome of a test run: matches, writes, and table rows. */
 interface SubgraphTestResult {
 	ok: boolean;
 	code?: "EMPTY_MAPPING" | "NO_EVENTS" | "NO_SOURCES";
@@ -809,6 +858,7 @@ interface SubgraphTestResult {
 	/** Keys present on every matched IN and never written to any OUT column. */
 	unusedInKeys?: string[];
 }
+/** A subgraph's schema, handlers, sources, and the events to run. */
 interface RunSubgraphTestInput {
 	schema: SubgraphSchema;
 	handlers: Record<string, unknown>;
@@ -828,6 +878,7 @@ declare function toContractCallPayload(row: IndexContractCallRow): Record<string
 * with zero written rows is EMPTY_MAPPING (the bns-names field-mapping shape).
 */
 declare function runSubgraphTest(input: RunSubgraphTestInput): Promise<SubgraphTestResult>;
+/** A subgraph's schema, sources, and handlers, for a probe run. */
 interface ProbeHandlersDef {
 	schema: SubgraphSchema;
 	sources: Record<string, {
@@ -836,6 +887,7 @@ interface ProbeHandlersDef {
 	}>;
 	handlers: Record<string, unknown>;
 }
+/** How many events matched and rows a probe wrote. */
 interface ProbeHandlersResult {
 	matched: number;
 	written: number;

package/dist/testing/index.js

@@ -1449,7 +1449,7 @@ import { createHash as createHash2 } 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: {
@@ -1505,12 +1505,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"
@@ -3076,5 +3077,5 @@ export {
   toHandlerPayload
 };
 
-//# debugId=3C4523A2FFBCFA3864756E2164756E21
+//# debugId=8313A9F6047DE2E064756E2164756E21
 //# sourceMappingURL=index.js.map