@subsquid/util-internal-data-source 0.0.0

package/lib/index.d.ts

@@ -0,0 +1,42 @@
+import type { FiniteRange } from '@subsquid/util-internal-range';
+export interface BlockRef {
+    number: number;
+    hash: string;
+}
+export interface StreamRequest {
+    from: number;
+    to?: number;
+    parentHash?: string;
+}
+/**
+ * @deprecated Use {@link StreamRequest} instead.
+ */
+export type DataSourceStreamOptions = StreamRequest;
+export interface BlockBatch<B> {
+    blocks: B[];
+    finalizedHead?: BlockRef;
+}
+export type BlockStream<B> = AsyncIterable<BlockBatch<B>>;
+export interface DataSource<B> {
+    getHead(): Promise<BlockRef>;
+    getFinalizedHead(): Promise<BlockRef>;
+    getFinalizedStream(req: StreamRequest): BlockStream<B>;
+    getStream(req: StreamRequest): BlockStream<B>;
+    getBlocksCountInRange?(range: FiniteRange): number;
+}
+export declare class ForkException extends Error {
+    readonly expectedParentHash: string;
+    readonly previousBlocks: BlockRef[];
+    readonly isSqdForkException = true;
+    constructor(blockNumber: number, expectedParentHash: string, previousBlocks: BlockRef[]);
+    get name(): string;
+}
+export declare function isForkException(err: unknown): err is ForkException;
+export declare class DataConsistencyError extends Error {
+    readonly isSqdDataConsistencyError = true;
+}
+export declare class BlockConsistencyError extends DataConsistencyError {
+    constructor(ref: BlockRef, errorMsg?: string);
+}
+export declare function isDataConsistencyError(err: unknown): err is Error;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,+BAA+B,CAAA;AAG9D,MAAM,WAAW,QAAQ;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACf;AAGD,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAGD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,aAAa,CAAA;AAGnD,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB,MAAM,EAAE,CAAC,EAAE,CAAA;IACX,aAAa,CAAC,EAAE,QAAQ,CAAA;CAC3B;AAGD,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;AAGzD,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAA;IAE5B,gBAAgB,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAA;IAGrC,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAEtD,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAE7C,qBAAqB,CAAC,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAAA;CACrD;AAGD,qBAAa,aAAc,SAAQ,KAAK;aAKhB,kBAAkB,EAAE,MAAM;aAC1B,cAAc,EAAE,QAAQ,EAAE;IAL9C,QAAQ,CAAC,kBAAkB,QAAO;gBAG9B,WAAW,EAAE,MAAM,EACH,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,QAAQ,EAAE;IAO9C,IAAI,IAAI,IAAI,MAAM,CAEjB;CACJ;AAGD,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,aAAa,CAElE;AAGD,qBAAa,oBAAqB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,yBAAyB,QAAO;CAC5C;AAGD,qBAAa,qBAAsB,SAAQ,oBAAoB;gBAC/C,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM;CAO/C;AAGD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,KAAK,CAEjE"}

package/lib/index.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlockConsistencyError = exports.DataConsistencyError = exports.ForkException = void 0;
+exports.isForkException = isForkException;
+exports.isDataConsistencyError = isDataConsistencyError;
+const assert_1 = __importDefault(require("assert"));
+class ForkException extends Error {
+    constructor(blockNumber, expectedParentHash, previousBlocks) {
+        (0, assert_1.default)(previousBlocks.length > 0);
+        let last = previousBlocks[previousBlocks.length - 1];
+        super(`expected ${blockNumber} to have parent ${last.number}#${expectedParentHash}, but got ${last.number}#${last.hash}`);
+        this.expectedParentHash = expectedParentHash;
+        this.previousBlocks = previousBlocks;
+        this.isSqdForkException = true;
+    }
+    get name() {
+        return 'ForkException';
+    }
+}
+exports.ForkException = ForkException;
+function isForkException(err) {
+    return err instanceof Error && !!err.isSqdForkException;
+}
+class DataConsistencyError extends Error {
+    constructor() {
+        super(...arguments);
+        this.isSqdDataConsistencyError = true;
+    }
+}
+exports.DataConsistencyError = DataConsistencyError;
+class BlockConsistencyError extends DataConsistencyError {
+    constructor(ref, errorMsg) {
+        let msg = `Failed to fetch block ${ref.number}#${ref.hash}`;
+        if (errorMsg) {
+            msg += ': ' + errorMsg;
+        }
+        super(msg);
+    }
+}
+exports.BlockConsistencyError = BlockConsistencyError;
+function isDataConsistencyError(err) {
+    return err instanceof Error && !!err.isSqdDataConsistencyError;
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAiEA,0CAEC;AAmBD,wDAEC;AAxFD,oDAA2B;AA8C3B,MAAa,aAAc,SAAQ,KAAK;IAGpC,YACI,WAAmB,EACH,kBAA0B,EAC1B,cAA0B;QAE1C,IAAA,gBAAM,EAAC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACjC,IAAI,IAAI,GAAG,cAAc,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACpD,KAAK,CAAC,YAAY,WAAW,mBAAmB,IAAI,CAAC,MAAM,IAAI,kBAAkB,aAAa,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;QALzG,uBAAkB,GAAlB,kBAAkB,CAAQ;QAC1B,mBAAc,GAAd,cAAc,CAAY;QALrC,uBAAkB,GAAG,IAAI,CAAA;IAUlC,CAAC;IAED,IAAI,IAAI;QACJ,OAAO,eAAe,CAAA;IAC1B,CAAC;CACJ;AAhBD,sCAgBC;AAGD,SAAgB,eAAe,CAAC,GAAY;IACxC,OAAO,GAAG,YAAY,KAAK,IAAI,CAAC,CAAE,GAAW,CAAC,kBAAkB,CAAA;AACpE,CAAC;AAGD,MAAa,oBAAqB,SAAQ,KAAK;IAA/C;;QACa,8BAAyB,GAAG,IAAI,CAAA;IAC7C,CAAC;CAAA;AAFD,oDAEC;AAGD,MAAa,qBAAsB,SAAQ,oBAAoB;IAC3D,YAAY,GAAa,EAAE,QAAiB;QACxC,IAAI,GAAG,GAAG,yBAAyB,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAA;QAC3D,IAAI,QAAQ,EAAE,CAAC;YACX,GAAG,IAAI,IAAI,GAAG,QAAQ,CAAA;QAC1B,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,CAAA;IACd,CAAC;CACJ;AARD,sDAQC;AAGD,SAAgB,sBAAsB,CAAC,GAAY;IAC/C,OAAO,GAAG,YAAY,KAAK,IAAI,CAAC,CAAE,GAAW,CAAC,yBAAyB,CAAA;AAC3E,CAAC"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@subsquid/util-internal-data-source",
+  "version": "0.0.0",
+  "description": "Definition of DataSource abstraction",
+  "license": "GPL-3.0-or-later",
+  "repository": "git@github.com:subsquid/squid-sdk.git",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@subsquid/util-internal-range": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "5.5.4",
+    "vitest": "4.1.5"
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc",
+    "test": "vitest --run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+import assert from 'assert'
+import type {FiniteRange} from '@subsquid/util-internal-range'
+
+
+export interface BlockRef {
+    number: number
+    hash: string
+}
+
+
+export interface StreamRequest {
+    from: number
+    to?: number
+    parentHash?: string
+}
+
+
+/**
+ * @deprecated Use {@link StreamRequest} instead.
+ */
+export type DataSourceStreamOptions = StreamRequest
+
+
+export interface BlockBatch<B> {
+    blocks: B[]
+    finalizedHead?: BlockRef
+}
+
+
+export type BlockStream<B> = AsyncIterable<BlockBatch<B>>
+
+
+export interface DataSource<B> {
+    getHead(): Promise<BlockRef>
+
+    getFinalizedHead(): Promise<BlockRef>
+    
+    // FIXME: maybe it's better to pass it as an option to `getStream`
+    getFinalizedStream(req: StreamRequest): BlockStream<B>
+
+    getStream(req: StreamRequest): BlockStream<B>
+
+    getBlocksCountInRange?(range: FiniteRange): number
+}
+
+
+export class ForkException extends Error {
+    readonly isSqdForkException = true
+
+    constructor(
+        blockNumber: number,
+        public readonly expectedParentHash: string,
+        public readonly previousBlocks: BlockRef[]
+    ) {
+        assert(previousBlocks.length > 0)
+        let last = previousBlocks[previousBlocks.length - 1]
+        super(`expected ${blockNumber} to have parent ${last.number}#${expectedParentHash}, but got ${last.number}#${last.hash}`)
+    }
+
+    get name(): string {
+        return 'ForkException'
+    }
+}
+
+
+export function isForkException(err: unknown): err is ForkException {
+    return err instanceof Error && !!(err as any).isSqdForkException
+}
+
+
+export class DataConsistencyError extends Error {
+    readonly isSqdDataConsistencyError = true
+}
+
+
+export class BlockConsistencyError extends DataConsistencyError {
+    constructor(ref: BlockRef, errorMsg?: string) {
+        let msg = `Failed to fetch block ${ref.number}#${ref.hash}`
+        if (errorMsg) {
+            msg += ': ' + errorMsg
+        }
+        super(msg)
+    }
+}
+
+
+export function isDataConsistencyError(err: unknown): err is Error {
+    return err instanceof Error && !!(err as any).isSqdDataConsistencyError
+}