() {
238 | let baseUrl = "";
239 | let defaultInit: RequestInit = {};
240 | const middlewares: Middleware[] = [];
241 | const fetch = wrapMiddlewares(middlewares, fetchJson);
242 |
243 | return {
244 | configure: (config: FetchConfig) => {
245 | baseUrl = config.baseUrl ?? "";
246 | defaultInit = config.init ?? {};
247 | middlewares.splice(0);
248 | middlewares.push(...(config.use ?? []));
249 | },
250 | use: (mw: Middleware) => middlewares.push(mw),
251 | path: (path: P) => ({
252 | method: (method: M) => ({
253 | create: ((queryParams?: Record) =>
254 | createFetch(
255 | async (payload, init) =>
256 | await fetchUrl({
257 | baseUrl: baseUrl ?? "",
258 | path: path as string,
259 | method: method as Method,
260 | queryParams: Object.keys(queryParams != null || {}),
261 | payload,
262 | init: mergeRequestInit(defaultInit, init),
263 | fetch,
264 | })
265 | )) as CreateFetch,
266 | }),
267 | }),
268 | };
269 | }
270 |
271 | export const Fetcher = {
272 | for: >() => fetcher(),
273 | };
274 |
--------------------------------------------------------------------------------
/test/thirdparty.test.ts:
--------------------------------------------------------------------------------
1 | /* eslint-disable @typescript-eslint/no-non-null-assertion */
2 | import { deepStrictEqual, strictEqual } from "assert";
3 | import { describe, test } from "mocha";
4 | import { getAccounts } from "@tableland/local";
5 | import {
6 | D1Orm,
7 | DataTypes,
8 | Model,
9 | GenerateQuery,
10 | QueryType,
11 | type Infer,
12 | } from "d1-orm";
13 | import sql, { type FormatConfig } from "@databases/sql";
14 | import { escapeSQLiteIdentifier } from "@databases/escape-identifier";
15 | import { NonceManager } from "@ethersproject/experimental";
16 | import { getDefaultProvider } from "../src/helpers/index.js";
17 | import { Database } from "../src/index.js";
18 | import { TEST_TIMEOUT_FACTOR } from "./setup";
19 |
20 | describe("thirdparty", function () {
21 | this.timeout(TEST_TIMEOUT_FACTOR * 10000);
22 |
23 | // Note that we're using the second account here
24 | const [, wallet] = getAccounts();
25 | const provider = getDefaultProvider("http://127.0.0.1:8545");
26 | // const signer = wallet.connect(provider);
27 | const baseSigner = wallet.connect(provider);
28 | // Also demonstrates the nonce manager usage
29 | const signer = new NonceManager(baseSigner);
30 | const db = new Database({ signer });
31 |
32 | describe("d1-orm", function () {
33 | const orm = new D1Orm(db);
34 |
35 | // We'll define our core model up here and use it in tests below
36 | const users = new Model(
37 | {
38 | D1Orm: orm,
39 | tableName: "users",
40 | primaryKeys: "id",
41 | uniqueKeys: [["email"]],
42 | },
43 | {
44 | id: {
45 | type: DataTypes.INTEGER,
46 | notNull: true,
47 | },
48 | name: {
49 | type: DataTypes.STRING,
50 | notNull: true,
51 | // See https://github.com/Interactions-as-a-Service/d1-orm/issues/60
52 | // defaultValue: "John Doe",
53 | },
54 | email: {
55 | type: DataTypes.STRING,
56 | },
57 | }
58 | );
59 | type User = Infer;
60 |
61 | this.beforeAll(async function () {
62 | const create = await users.CreateTable({
63 | strategy: "default",
64 | });
65 | await create.meta.txn.wait();
66 |
67 | // TODO: Find a nicer way to deal with this...
68 | (users.tableName as any) = create.meta.txn.name;
69 | });
70 |
71 | test("where a basic model is used to create data", async function () {
72 | await users.InsertOne({
73 | name: "Bobby Tables",
74 | email: "bobby-tab@gmail.com",
75 | });
76 |
77 | const [result] = await users.InsertMany([
78 | {
79 | name: "Bobby Tables",
80 | email: "bob-tables@gmail.com",
81 | },
82 | {
83 | name: "Jane Tables",
84 | email: "janet@gmail.com",
85 | },
86 | ]);
87 |
88 | await result.meta.txn.wait();
89 |
90 | const { results } = await users.All({
91 | where: { name: "Bobby Tables" },
92 | limit: 1,
93 | offset: 0,
94 | orderBy: ["id"],
95 | });
96 |
97 | deepStrictEqual(results, [
98 | {
99 | name: "Bobby Tables",
100 | id: 1,
101 | email: "bobby-tab@gmail.com",
102 | },
103 | ]);
104 | });
105 |
106 | test("basic query building works well to then query the data", async function () {
107 | const { query, bindings } = GenerateQuery(
108 | QueryType.SELECT,
109 | users.tableName, // Could also come from the above meta.txn objects
110 | {
111 | where: {
112 | name: "Bobby Tables",
113 | }, // this uses the type from above to enforce it to properties which exist on the table
114 | limit: 1, // we only want the first user
115 | offset: 1, // skip the first user named 'Bobby Tables' when performing this query
116 |
117 | // Using orderBy is a special case, so there's a few possible syntaxes for it
118 | orderBy: { column: "id", descending: true }, // ORDER BY id DESC NULLS LAST
119 | }
120 | );
121 |
122 | // Using the database directly
123 | const stmt = db.prepare(query).bind(bindings);
124 | const { results } = await stmt.all();
125 | deepStrictEqual(results, [
126 | {
127 | name: "Bobby Tables",
128 | id: 1,
129 | email: "bobby-tab@gmail.com",
130 | },
131 | ]);
132 | });
133 |
134 | test("where upserts are easier when using an orm", async function () {
135 | const user: User = {
136 | id: 1,
137 | name: "John Doe",
138 | email: "john-doe@gmail.com",
139 | };
140 | const { query, bindings } = GenerateQuery(
141 | QueryType.UPSERT,
142 | users.tableName, // Could also come from the above meta.txn objects
143 | {
144 | data: user,
145 | upsertOnlyUpdateData: {
146 | name: user.name,
147 | email: user.email,
148 | },
149 | where: {
150 | id: user.id,
151 | },
152 | },
153 | "id"
154 | );
155 | // {
156 | // query: "INSERT INTO users (id, name, email) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET name = ?, email = ? WHERE id = ?",
157 | // bindings: [1, "John Doe", "john-doe@gmail.com", "John Doe", "john-doe@gmail.com", 1]
158 | // }
159 |
160 | // Using the database directly
161 | const stmt = db.prepare(query).bind(bindings);
162 | const { meta } = await stmt.run();
163 | const receipt = await (meta.txn as any).wait();
164 | strictEqual(receipt?.error, undefined);
165 |
166 | const results = await db
167 | .prepare(`SELECT * FROM ${users.tableName} WHERE id=?`)
168 | .bind(user.id)
169 | .first();
170 | deepStrictEqual(results, user);
171 | });
172 | });
173 |
174 | describe("@databases/sql", function () {
175 | // See https://www.atdatabases.org/docs/sqlite
176 | const sqliteFormat: FormatConfig = {
177 | escapeIdentifier: (str) => escapeSQLiteIdentifier(str),
178 | formatValue: (value) => ({ placeholder: "?", value }),
179 | };
180 | let tableName: string;
181 |
182 | this.beforeAll(async function () {
183 | this.timeout(TEST_TIMEOUT_FACTOR * 10000);
184 |
185 | // First, we'll test out using sql identifiers
186 | const primaryKey = sql.ident("id");
187 | const query = sql`CREATE TABLE test_sql (${primaryKey} integer primary key, counter integer, info text);`;
188 | const { text, values } = query.format(sqliteFormat);
189 | const { meta } = await db.prepare(text).bind(values).run();
190 | const { name } = await meta.txn!.wait();
191 | tableName = name!;
192 | });
193 |
194 | test("inserting rows with interpolated values is possible", async function () {
195 | const one = 1;
196 | const four = 4;
197 | const three = sql.value("three");
198 | // Here's a safer way to inject table names
199 | const query = sql`INSERT INTO ${sql.ident(
200 | tableName
201 | )} (counter, ${sql.ident("info")})
202 | VALUES (${one}, 'one'), (2, 'two'), (3, ${three}), (${four}, 'four');`;
203 | const { text, values } = query.format(sqliteFormat);
204 | const { meta } = await db.prepare(text).bind(values).run();
205 | await meta.txn?.wait();
206 | strictEqual(typeof meta.txn?.transactionHash, "string");
207 | strictEqual(meta.txn?.transactionHash.length, 66);
208 | strictEqual(meta.duration > 0, true);
209 | });
210 |
211 | test("querying is quite easy when using @database/sql", async function () {
212 | const boundValue = 3;
213 | const query = sql`SELECT * FROM ${sql.ident(
214 | tableName
215 | )} WHERE counter >= ${boundValue};`;
216 | const { text, values } = query.format(sqliteFormat);
217 | const { results } = await db.prepare(text).bind(values).all();
218 | deepStrictEqual(results, [
219 | { id: 3, counter: 3, info: "three" },
220 | { id: 4, counter: 4, info: "four" },
221 | ]);
222 | });
223 | });
224 | });
225 |
--------------------------------------------------------------------------------
/test/aliases.test.ts:
--------------------------------------------------------------------------------
1 | import url from "node:url";
2 | import path from "node:path";
3 | import fs from "node:fs";
4 | /* eslint-disable @typescript-eslint/no-non-null-assertion */
5 | import { strictEqual, rejects } from "assert";
6 | import { describe, test } from "mocha";
7 | import { getAccounts } from "@tableland/local";
8 | import {
9 | type NameMapping,
10 | getDefaultProvider,
11 | jsonFileAliases,
12 | } from "../src/helpers/index.js";
13 | import { Database } from "../src/index.js";
14 | import { TEST_TIMEOUT_FACTOR } from "./setup";
15 |
16 | /* eslint-disable @typescript-eslint/naming-convention */
17 | const __dirname = url.fileURLToPath(new URL(".", import.meta.url));
18 |
19 | describe("aliases", function () {
20 | this.timeout(TEST_TIMEOUT_FACTOR * 10000);
21 | // Note that we're using the second account here
22 | const [, wallet] = getAccounts();
23 | const provider = getDefaultProvider("http://127.0.0.1:8545");
24 | const signer = wallet.connect(provider);
25 |
26 | describe("in memory aliases", function () {
27 | // keeping name mappings in memory during these tests, but in practice
28 | // this map needs to be persisted for the entire life of the aliases
29 | const nameMap: NameMapping = {};
30 |
31 | const db = new Database({
32 | signer,
33 | // this parameter is the core of the aliases feature
34 | aliases: {
35 | read: async function () {
36 | return nameMap;
37 | },
38 | write: async function (names) {
39 | for (const uuTableName in names) {
40 | nameMap[uuTableName] = names[uuTableName];
41 | }
42 | },
43 | },
44 | });
45 |
46 | test("running create statement adds name to aliases", async function () {
47 | const tablePrefix = "aliases_table";
48 | const { meta } = await db
49 | .prepare(`CREATE TABLE ${tablePrefix} (counter int, info text);`)
50 | .all();
51 | const uuTableName = meta.txn?.name ?? "";
52 |
53 | strictEqual(nameMap[tablePrefix], uuTableName);
54 | });
55 |
56 | test("insert and select uses aliases table name mappings", async function () {
57 | await db
58 | .prepare(
59 | "CREATE TABLE students (first_name text, last_name text);"
60 | // testing`first` here
61 | )
62 | .first();
63 |
64 | const { meta } = await db
65 | .prepare(
66 | "INSERT INTO students (first_name, last_name) VALUES ('Bobby', 'Tables');"
67 | // testing`run` here
68 | )
69 | .run();
70 |
71 | await meta.txn?.wait();
72 |
73 | const { results } = await db
74 | .prepare(
75 | `SELECT * FROM students;`
76 | // testing `all` here
77 | // with 'run' and 'first' above this touches all of the single statement methods
78 | )
79 | .all<{ first_name: string; last_name: string }>();
80 |
81 | strictEqual(results.length, 1);
82 | strictEqual(results[0].first_name, "Bobby");
83 | strictEqual(results[0].last_name, "Tables");
84 | });
85 |
86 | test("batch create uses aliases table name mappings", async function () {
87 | const prefixes = ["batch_table1", "batch_table2", "batch_table3"];
88 |
89 | const [{ meta }] = await db.batch([
90 | db.prepare(`CREATE TABLE ${prefixes[0]} (counter int, info text);`),
91 | db.prepare(`CREATE TABLE ${prefixes[1]} (counter int, info text);`),
92 | db.prepare(`CREATE TABLE ${prefixes[2]} (counter int, info text);`),
93 | ]);
94 |
95 | const uuNames = meta.txn?.names ?? [];
96 |
97 | strictEqual(nameMap[prefixes[0]], uuNames[0]);
98 | strictEqual(nameMap[prefixes[1]], uuNames[1]);
99 | strictEqual(nameMap[prefixes[2]], uuNames[2]);
100 | });
101 |
102 | test("batch mutate uses aliases table name mappings", async function () {
103 | await db.prepare("CREATE TABLE mutate_test (k text, val text);").first();
104 |
105 | const [{ meta }] = await db.batch([
106 | db.prepare(
107 | "INSERT INTO mutate_test (k, val) VALUES ('token1', 'asdfgh');"
108 | ),
109 | db.prepare(
110 | "INSERT INTO mutate_test (k, val) VALUES ('token2', 'qwerty');"
111 | ),
112 | db.prepare(
113 | "INSERT INTO mutate_test (k, val) VALUES ('token3', 'zxcvbn');"
114 | ),
115 | ]);
116 |
117 | await meta.txn?.wait();
118 |
119 | const { results } = await db
120 | .prepare(`SELECT * FROM mutate_test;`)
121 | .all<{ k: string; val: string }>();
122 |
123 | strictEqual(results.length, 3);
124 | strictEqual(results[0].k, "token1");
125 | strictEqual(results[1].k, "token2");
126 | strictEqual(results[2].k, "token3");
127 | strictEqual(results[0].val, "asdfgh");
128 | strictEqual(results[1].val, "qwerty");
129 | strictEqual(results[2].val, "zxcvbn");
130 | });
131 |
132 | test("batch select uses aliases table name mappings", async function () {
133 | const prefixes = ["batch_select1", "batch_select2", "batch_select3"];
134 |
135 | await db.batch([
136 | db.prepare(`CREATE TABLE ${prefixes[0]} (counter int);`),
137 | db.prepare(`CREATE TABLE ${prefixes[1]} (counter int);`),
138 | db.prepare(`CREATE TABLE ${prefixes[2]} (counter int);`),
139 | ]);
140 |
141 | const [{ meta }] = await db.batch([
142 | db.prepare(`INSERT INTO ${prefixes[0]} (counter) VALUES (1);`),
143 | db.prepare(`INSERT INTO ${prefixes[1]} (counter) VALUES (2);`),
144 | db.prepare(`INSERT INTO ${prefixes[2]} (counter) VALUES (3);`),
145 | ]);
146 |
147 | await meta.txn?.wait();
148 |
149 | const results = await db.batch<{ counter: number }>([
150 | db.prepare(`SELECT * FROM ${prefixes[0]};`),
151 | db.prepare(`SELECT * FROM ${prefixes[1]};`),
152 | db.prepare(`SELECT * FROM ${prefixes[2]};`),
153 | ]);
154 |
155 | strictEqual(results.length, 3);
156 | strictEqual(results[0].results.length, 1);
157 | strictEqual(results[1].results.length, 1);
158 | strictEqual(results[2].results.length, 1);
159 | strictEqual(results[0].results[0].counter, 1);
160 | strictEqual(results[1].results[0].counter, 2);
161 | strictEqual(results[2].results[0].counter, 3);
162 | });
163 |
164 | test("using universal unique table name works with aliases", async function () {
165 | const { meta } = await db
166 | .prepare("CREATE TABLE uu_name (counter int);")
167 | .all();
168 | const uuTableName = meta.txn?.name ?? "";
169 |
170 | const { meta: insertMeta } = await db
171 | .prepare(`INSERT INTO ${uuTableName} (counter) VALUES (1);`)
172 | .all();
173 |
174 | await insertMeta.txn?.wait();
175 |
176 | const { results } = await db
177 | .prepare(`SELECT * FROM ${uuTableName};`)
178 | .all<{ counter: number }>();
179 |
180 | strictEqual(results.length, 1);
181 | strictEqual(results[0].counter, 1);
182 | });
183 |
184 | test("creating a table with an existing prefix throws", async function () {
185 | const tablePrefix = "duplicate_name";
186 | await db
187 | .prepare(`CREATE TABLE ${tablePrefix} (counter int, info text);`)
188 | .all();
189 |
190 | await rejects(
191 | db
192 | .prepare(`CREATE TABLE ${tablePrefix} (counter int, info text);`)
193 | .all(),
194 | "table name already exists in aliases"
195 | );
196 | });
197 | });
198 |
199 | describe("json file aliases", function () {
200 | const aliasesDir = path.join(__dirname, "aliases");
201 | const aliasesFile = path.join(aliasesDir, "json-file-aliases.json");
202 | try {
203 | fs.mkdirSync(aliasesDir);
204 | } catch (err) {}
205 | // reset the aliases file, and ensure the helper
206 | // creates the file if it doesn't exist
207 | try {
208 | fs.unlinkSync(aliasesFile);
209 | } catch (err) {}
210 |
211 | const db = new Database({
212 | signer,
213 | // use the built-in SDK helper to setup and manage json aliases files
214 | aliases: jsonFileAliases(aliasesFile),
215 | });
216 |
217 | this.afterAll(function () {
218 | try {
219 | fs.unlinkSync(aliasesFile);
220 | } catch (err) {}
221 | });
222 |
223 | test("running create statement adds name to aliases", async function () {
224 | const tablePrefix = "json_aliases_table";
225 | const { meta } = await db
226 | .prepare(`CREATE TABLE ${tablePrefix} (counter int, info text);`)
227 | .all();
228 |
229 | const uuTableName = meta.txn?.name ?? "";
230 | const nameMap = (await db.config.aliases?.read()) ?? {};
231 |
232 | strictEqual(nameMap[tablePrefix], uuTableName);
233 | });
234 | });
235 | });
236 |
--------------------------------------------------------------------------------
/src/registry/utils.ts:
--------------------------------------------------------------------------------
1 | import {
2 | type TransactionReceipt,
3 | pollTransactionReceipt,
4 | } from "../validator/receipt.js";
5 | import { type Runnable } from "../registry/index.js";
6 | import { normalize } from "../helpers/index.js";
7 | import { type SignalAndInterval, type Wait } from "../helpers/await.js";
8 | import {
9 | type Config,
10 | type ReadConfig,
11 | extractBaseUrl,
12 | extractChainId,
13 | } from "../helpers/config.js";
14 | import {
15 | type ContractTransaction,
16 | getContractReceipt,
17 | } from "../helpers/ethers.js";
18 | import { validateTables, type StatementType } from "../helpers/parser.js";
19 |
20 | /**
21 | * WaitableTransactionReceipt represents a named TransactionReceipt with a wait method.
22 | * See the Validator spec in the docs for more details.
23 | * @typedef {Object} WaitableTransactionReceipt
24 | * @property {function} wait - Async function that will not return until the validator has processed tx.
25 | * @property {string} name - The full table name.
26 | * @property {string} prefix - The table name prefix.
27 | * @property {number} chainId - The chainId of tx.
28 | * @property {string} tableId - The tableId of tx.
29 | * @property {string} transaction_hash - The transaction hash of tx.
30 | * @property {number} block_number - The block number of tx.
31 | * @property {Object} error - The first error encounntered when the Validator processed tx.
32 | * @property {number} error_event_idx - The index of the event that cause the error when the Validator processed tx.
33 | */
34 | export type WaitableTransactionReceipt = TransactionReceipt &
35 | Wait &
36 | Named;
37 |
38 | /**
39 | * Named represents a named table with a prefix.
40 | */
41 | export interface Named {
42 | /**
43 | * @custom:deprecated First table's full name.
44 | */
45 | name: string;
46 | /**
47 | * @custom:deprecated First table name prefix.
48 | */
49 | prefix: string;
50 | /**
51 | * The full table names
52 | */
53 | names: string[];
54 | /**
55 | * The table prefixes
56 | */
57 | prefixes: string[];
58 | }
59 |
60 | /**
61 | * ExtractedStatement represents a SQL statement string with the type and tables extracted.
62 | */
63 | export interface ExtractedStatement {
64 | /**
65 | * SQL statement string.
66 | */
67 | sql: string;
68 | /**
69 | * List of table names referenced within the statement.
70 | */
71 | tables: string[];
72 | /**
73 | * The statement type. Must be one of "read", "write", "create", or "acl".
74 | */
75 | type: StatementType;
76 | }
77 |
78 | function isTransactionReceipt(arg: any): arg is WaitableTransactionReceipt {
79 | return (
80 | !Array.isArray(arg) &&
81 | arg.transactionHash != null &&
82 | arg.tableId != null &&
83 | arg.chainId != null &&
84 | arg.blockNumber != null &&
85 | typeof arg.wait === "function"
86 | );
87 | }
88 |
89 | export function wrapResult(
90 | resultsOrReceipt: T[] | WaitableTransactionReceipt,
91 | duration: number
92 | ): Result {
93 | const meta: Metadata = { duration };
94 | const result: Result = {
95 | meta,
96 | success: true,
97 | results: [],
98 | };
99 | if (isTransactionReceipt(resultsOrReceipt)) {
100 | return { ...result, meta: { ...meta, txn: resultsOrReceipt } };
101 | }
102 | return { ...result, results: resultsOrReceipt };
103 | }
104 |
105 | /**
106 | * Metadata represents meta information about an executed statement/transaction.
107 | */
108 | export interface Metadata {
109 | /**
110 | * Total client-side duration of the async call.
111 | */
112 | duration: number;
113 | /**
114 | * The optional transactionn information receipt.
115 | */
116 | txn?: WaitableTransactionReceipt;
117 | /**
118 | * Metadata may contrain additional arbitrary key/values pairs.
119 | */
120 | [key: string]: any;
121 | }
122 |
123 | /**
124 | * Result represents the core return result for an executed statement.
125 | */
126 | export interface Result {
127 | /**
128 | * Possibly empty list of query results.
129 | */
130 | results: T[];
131 | /**
132 | * Whether the query or transaction was successful.
133 | */
134 | success: boolean; // almost always true
135 | /**
136 | * If there was an error, this will contain the error string.
137 | */
138 | error?: string;
139 | /**
140 | * Additional meta information.
141 | */
142 | meta: Metadata;
143 | }
144 |
145 | export async function extractReadonly(
146 | conn: Config,
147 | { tables, type }: Omit
148 | ): Promise {
149 | const [{ chainId }] = await validateTables({ tables, type });
150 | const baseUrl = await extractBaseUrl(conn, chainId);
151 | return { baseUrl };
152 | }
153 |
154 | /**
155 | * Given a config, a table name prefix, and a transaction that only affects a single table
156 | * this will enable waiting for the Validator to materialize the change in the transaction
157 | * @param {Object} conn - A Database config.
158 | * @param {string} prefix - A table name prefix.
159 | * @param {Object} tx - A transaction object that includes a call to the Registry Contract.
160 | * @returns {WaitableTransactionReceipt}
161 | */
162 | export async function wrapTransaction(
163 | conn: Config,
164 | prefix: string,
165 | tx: ContractTransaction
166 | ): Promise {
167 | // TODO: next major we should combine this with wrapManyTransaction
168 | const _params = await getContractReceipt(tx);
169 | const chainId =
170 | _params.chainId === 0 || _params.chainId == null
171 | ? await extractChainId(conn)
172 | : _params.chainId;
173 | const name = `${prefix}_${chainId}_${_params.tableIds[0]}`;
174 | const params = { ..._params, chainId, tableId: _params.tableIds[0] };
175 | const wait = async (
176 | opts: SignalAndInterval = {}
177 | ): Promise => {
178 | const receipt = await pollTransactionReceipt(conn, params, opts);
179 | if (receipt.error != null) {
180 | throw new Error(receipt.error);
181 | }
182 | return { ...receipt, name, prefix, prefixes: [prefix], names: [name] };
183 | };
184 | return { ...params, wait, name, prefix, prefixes: [prefix], names: [name] };
185 | }
186 |
187 | /* A helper function for mapping contract event receipts to table data
188 | *
189 | * @param {conn} a database config object
190 | * @param {statements} either the sql statement strings or the nomralized statement objects that were used in the transaction
191 | * @param {tx} the transaction object
192 | * @returns {(WaitableTransactionReceipt & Named)}
193 | *
194 | */
195 | export async function wrapManyTransaction(
196 | conn: Config,
197 | statements: string[] | Runnable[],
198 | tx: ContractTransaction
199 | ): Promise {
200 | const _params = await getContractReceipt(tx);
201 | const chainId =
202 | _params.chainId === 0 || _params.chainId == null
203 | ? await extractChainId(conn)
204 | : _params.chainId;
205 |
206 | // map the transaction events to table names and prefixes then return them to the caller
207 | const { names, prefixes } = (
208 | await Promise.all(
209 | _params.tableIds.map(async function (tableId: string, i: number) {
210 | const statementString = isRunnable(statements[i])
211 | ? (statements[i] as Runnable).statement
212 | : (statements[i] as string);
213 | const normalized = await normalize(statementString);
214 |
215 | if (normalized.type === "create") {
216 | return {
217 | name: `${normalized.tables[0]}_${chainId}_${tableId}`,
218 | prefix: normalized.tables[0],
219 | };
220 | }
221 | return {
222 | name: normalized.tables[0],
223 | prefix: normalized.tables[0].split("_").slice(0, -2).join("_"),
224 | };
225 | })
226 | )
227 | ).reduce<{ prefixes: string[]; names: string[] }>(
228 | function (acc, cur) {
229 | acc.prefixes.push(cur.prefix);
230 | acc.names.push(cur.name);
231 | return acc;
232 | },
233 | { prefixes: [], names: [] }
234 | );
235 |
236 | const params = { ..._params, chainId };
237 | // TODO: including `name`, `prefix`, and `tableId` for back compat, will be removed next major
238 | const tableMeta = {
239 | names,
240 | name: names[0],
241 | tableId: _params.tableIds[0],
242 | prefixes,
243 | prefix: prefixes[0],
244 | };
245 |
246 | const wait = async (
247 | opts: SignalAndInterval = {}
248 | ): Promise => {
249 | const receipt = await pollTransactionReceipt(conn, params, opts);
250 | if (receipt.error != null) {
251 | throw new Error(receipt.error);
252 | }
253 |
254 | return {
255 | ...receipt,
256 | ...tableMeta,
257 | };
258 | };
259 |
260 | return {
261 | ...params,
262 | wait,
263 | ...tableMeta,
264 | };
265 | }
266 |
267 | function isRunnable(statement: string | Runnable): statement is Runnable {
268 | return (statement as Runnable).tableId !== undefined;
269 | }
270 |
--------------------------------------------------------------------------------
/src/validator/client/validator.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * This file was auto-generated by openapi-typescript.
3 | * Do not make direct changes to the file.
4 | */
5 |
6 |
7 | export interface paths {
8 | "/health": {
9 | /**
10 | * Get health status
11 | * @description Returns OK if the validator considers itself healthy.
12 | */
13 | get: operations["health"];
14 | };
15 | "/version": {
16 | /**
17 | * Get version information
18 | * @description Returns version information about the validator daemon.
19 | */
20 | get: operations["version"];
21 | };
22 | "/query": {
23 | /**
24 | * Query the network
25 | * @description Returns the results of a SQL read query against the Tabeland network
26 | */
27 | get: operations["queryByStatement"];
28 | };
29 | "/receipt/{chainId}/{transactionHash}": {
30 | /**
31 | * Get transaction status
32 | * @description Returns the status of a given transaction receipt by hash
33 | */
34 | get: operations["receiptByTransactionHash"];
35 | };
36 | "/tables/{chainId}/{tableId}": {
37 | /**
38 | * Get table information
39 | * @description Returns information about a single table, including schema information
40 | */
41 | get: operations["getTableById"];
42 | };
43 | }
44 |
45 | export type webhooks = Record;
46 |
47 | export interface components {
48 | schemas: {
49 | readonly Table: {
50 | /** @example healthbot_80001_1 */
51 | readonly name?: string;
52 | /** @example https://testnets.tableland.network/api/v1/tables/80001/1 */
53 | readonly external_url?: string;
54 | /** @example https://tables.testnets.tableland.xyz/80001/1.html */
55 | readonly animation_url?: string;
56 | /** @example https://tables.testnets.tableland.xyz/80001/1.svg */
57 | readonly image?: string;
58 | /**
59 | * @example {
60 | * "display_type": "date",
61 | * "trait_type": "created",
62 | * "value": 1657113720
63 | * }
64 | */
65 | readonly attributes?: readonly ({
66 | /** @description The display type for marketplaces */
67 | readonly display_type?: string;
68 | /** @description The trait type for marketplaces */
69 | readonly trait_type?: string;
70 | /** @description The value of the property */
71 | readonly value?: string | number | boolean | Record;
72 | })[];
73 | readonly schema?: components["schemas"]["Schema"];
74 | };
75 | readonly TransactionReceipt: {
76 | /**
77 | * @deprecated
78 | * @description This field is deprecated
79 | * @example 1
80 | */
81 | readonly table_id?: string;
82 | /**
83 | * @example [
84 | * "1",
85 | * "2"
86 | * ]
87 | */
88 | readonly table_ids?: readonly (string)[];
89 | /** @example 0x02f319429b8a7be1cbb492f0bfbf740d2472232a2edadde7df7c16c0b61aa78b */
90 | readonly transaction_hash?: string;
91 | /**
92 | * Format: int64
93 | * @example 27055540
94 | */
95 | readonly block_number?: number;
96 | /**
97 | * Format: int32
98 | * @example 80001
99 | */
100 | readonly chain_id?: number;
101 | /** @example The query statement is invalid */
102 | readonly error?: string;
103 | /**
104 | * Format: int32
105 | * @example 1
106 | */
107 | readonly error_event_idx?: number;
108 | };
109 | readonly Schema: {
110 | readonly columns?: readonly (components["schemas"]["Column"])[];
111 | /**
112 | * @example [
113 | * "PRIMARY KEY (id)"
114 | * ]
115 | */
116 | readonly table_constraints?: readonly (string)[];
117 | };
118 | readonly Column: {
119 | /** @example id */
120 | readonly name?: string;
121 | /** @example integer */
122 | readonly type?: string;
123 | /**
124 | * @example [
125 | * "NOT NULL",
126 | * "PRIMARY KEY",
127 | * "UNIQUE"
128 | * ]
129 | */
130 | readonly constraints?: readonly (string)[];
131 | };
132 | readonly VersionInfo: {
133 | /**
134 | * Format: int32
135 | * @example 0
136 | */
137 | readonly version?: number;
138 | /** @example 79688910d4689dcc0991a0d8eb9d988200586d8f */
139 | readonly git_commit?: string;
140 | /** @example foo/experimentalfeature */
141 | readonly git_branch?: string;
142 | /** @example dirty */
143 | readonly git_state?: string;
144 | /** @example v1.2.3_dirty */
145 | readonly git_summary?: string;
146 | /** @example 2022-11-29T16:28:04Z */
147 | readonly build_date?: string;
148 | /** @example v1.0.1 */
149 | readonly binary_version?: string;
150 | };
151 | };
152 | responses: never;
153 | parameters: never;
154 | requestBodies: never;
155 | headers: never;
156 | pathItems: never;
157 | }
158 |
159 | export type external = Record;
160 |
161 | export interface operations {
162 |
163 | /**
164 | * Get health status
165 | * @description Returns OK if the validator considers itself healthy.
166 | */
167 | health: {
168 | responses: {
169 | /** @description The validator is healthy. */
170 | 200: never;
171 | };
172 | };
173 | /**
174 | * Get version information
175 | * @description Returns version information about the validator daemon.
176 | */
177 | version: {
178 | responses: {
179 | /** @description successful operation */
180 | 200: {
181 | content: {
182 | readonly "application/json": components["schemas"]["VersionInfo"];
183 | };
184 | };
185 | };
186 | };
187 | /**
188 | * Query the network
189 | * @description Returns the results of a SQL read query against the Tabeland network
190 | */
191 | queryByStatement: {
192 | parameters: {
193 | query: {
194 | /**
195 | * @description The SQL read query statement
196 | * @example select * from healthbot_80001_1
197 | */
198 | statement: string;
199 | /**
200 | * @description The requested response format:
201 | * * `objects` - Returns the query results as a JSON array of JSON objects.
202 | * * `table` - Return the query results as a JSON object with columns and rows properties.
203 | */
204 | format?: "objects" | "table";
205 | /** @description Whether to extract the JSON object from the single property of the surrounding JSON object. */
206 | extract?: boolean;
207 | /** @description Whether to unwrap the returned JSON objects from their surrounding array. */
208 | unwrap?: boolean;
209 | };
210 | };
211 | responses: {
212 | /** @description Successful operation */
213 | 200: {
214 | content: {
215 | readonly "application/json": Record;
216 | };
217 | };
218 | /** @description Invalid query/statement value */
219 | 400: never;
220 | /** @description Row Not Found */
221 | 404: never;
222 | /** @description Too Many Requests */
223 | 429: never;
224 | };
225 | };
226 | /**
227 | * Get transaction status
228 | * @description Returns the status of a given transaction receipt by hash
229 | */
230 | receiptByTransactionHash: {
231 | parameters: {
232 | path: {
233 | /**
234 | * @description The parent chain to target
235 | * @example 80001
236 | */
237 | chainId: number;
238 | /**
239 | * @description The transaction hash to request
240 | * @example 0x02f319429b8a7be1cbb492f0bfbf740d2472232a2edadde7df7c16c0b61aa78b
241 | */
242 | transactionHash: string;
243 | };
244 | };
245 | responses: {
246 | /** @description successful operation */
247 | 200: {
248 | content: {
249 | readonly "application/json": components["schemas"]["TransactionReceipt"];
250 | };
251 | };
252 | /** @description Invalid chain identifier or transaction hash format */
253 | 400: never;
254 | /** @description No transaction receipt found with the provided hash */
255 | 404: never;
256 | /** @description Too Many Requests */
257 | 429: never;
258 | };
259 | };
260 | /**
261 | * Get table information
262 | * @description Returns information about a single table, including schema information
263 | */
264 | getTableById: {
265 | parameters: {
266 | path: {
267 | /**
268 | * @description The parent chain to target
269 | * @example 80001
270 | */
271 | chainId: number;
272 | /**
273 | * @description Table identifier
274 | * @example 1
275 | */
276 | tableId: string;
277 | };
278 | };
279 | responses: {
280 | /** @description successful operation */
281 | 200: {
282 | content: {
283 | readonly "application/json": components["schemas"]["Table"];
284 | };
285 | };
286 | /** @description Invalid chain or table identifier */
287 | 400: never;
288 | /** @description Table Not Found */
289 | 404: never;
290 | /** @description Too Many Requests */
291 | 429: never;
292 | /** @description Internal Server Error */
293 | 500: never;
294 | };
295 | };
296 | }
297 |
--------------------------------------------------------------------------------
/src/helpers/subscribe.ts:
--------------------------------------------------------------------------------
1 | import { EventEmitter } from "events";
2 | import asyncGenFromEmit from "@async-generators/from-emitter";
3 | import { type TablelandTables } from "@tableland/evm";
4 | import { pollTransactionReceipt } from "../validator/receipt.js";
5 | import {
6 | getTableIdentifier,
7 | getContractAndOverrides,
8 | type TableIdentifier,
9 | } from "../registry/contract.js";
10 | import { extractBaseUrl, type Config } from "../helpers/index.js";
11 |
12 | // @ts-expect-error Seems like this package isn't setup to work with modern esm + ts
13 | const fromEmitter = asyncGenFromEmit.default;
14 |
15 | type ContractMap = Record;
16 |
17 | interface ContractEventListener {
18 | eventName: string;
19 | eventListener: (...args: any[]) => void;
20 | }
21 |
22 | type ListenerMap = Record<
23 | // The key is the listenerId, which is _{chainId}_{tableId}
24 | string,
25 | {
26 | chainId: number;
27 | tableId: string;
28 | emitter: EventEmitter;
29 | contractListeners: ContractEventListener[];
30 | }
31 | >;
32 |
33 | type ContractEventTableIdMap = Record<
34 | // the key is the event name in the Solidity contract
35 | string,
36 | {
37 | // `tableIdIndex` is the index of the event's argument that contains the tableId
38 | tableIdIndex: number;
39 | // `emit` is the name of the event that will be emitted by the TableEventBus instance
40 | emit: string;
41 | }
42 | >;
43 |
44 | /**
45 | * List of the Registry Contract events that will be emitted from the TableEventBus.
46 | */
47 | const contractEvents: ContractEventTableIdMap = {
48 | RunSQL: {
49 | tableIdIndex: 2,
50 | emit: "change",
51 | },
52 | TransferTable: {
53 | tableIdIndex: 2,
54 | emit: "transfer",
55 | },
56 | SetController: {
57 | tableIdIndex: 0,
58 | emit: "set-controller",
59 | },
60 | };
61 |
62 | /**
63 | * TableEventBus provides a way to listen for:
64 | * mutations, transfers, and changes to controller
65 | */
66 | export class TableEventBus {
67 | readonly config: Config;
68 | readonly contracts: ContractMap;
69 | readonly listeners: ListenerMap;
70 |
71 | /**
72 | * Create a TableEventBus instance with the specified connection configuration.
73 | * @param config The connection configuration. This must include an ethersjs
74 | * Signer. If passing the config from a pre-existing Database instance, it
75 | * must have a non-null signer key defined.
76 | */
77 | constructor(config: Partial = {}) {
78 | /* c8 ignore next 3 */
79 | if (config.signer == null) {
80 | throw new Error("missing signer information");
81 | }
82 |
83 | this.config = config as Config;
84 | this.contracts = {};
85 | this.listeners = {};
86 | }
87 |
88 | /**
89 | * Start listening to the Registry Contract for events that are associated
90 | * with a given table.
91 | * There's only ever one "listener" for a table, but the emitter that
92 | * Contract listener has can have as many event listeners as the environment
93 | * supports.
94 | * @param tableName The full name of table that you want to listen for
95 | * changes to.
96 | */
97 | async addListener(tableName: string): Promise {
98 | if (tableName == null) {
99 | throw new Error("table name is required to add listener");
100 | }
101 |
102 | const tableIdentifier = await getTableIdentifier(tableName);
103 | const listenerId = `_${tableIdentifier.chainId}_${tableIdentifier.tableId}`;
104 | if (this.listeners[listenerId]?.emitter != null) {
105 | return this.listeners[listenerId].emitter;
106 | }
107 |
108 | const emitter = new EventEmitter();
109 |
110 | // If not already listening to the contract we will start listening now,
111 | // if already listening we will start tracking the new emitter.
112 | const contractEventListeners = await this._ensureListening(
113 | listenerId,
114 | emitter
115 | );
116 |
117 | this.listeners[listenerId] = {
118 | ...tableIdentifier,
119 | emitter,
120 | contractListeners: contractEventListeners,
121 | };
122 |
123 | return emitter;
124 | }
125 |
126 | /**
127 | * A simple wrapper around `addListener` that returns an async iterable
128 | * which can be used with the for await ... of pattern.
129 | * @param tableName The full name of table that you want to listen for
130 | * changes to.
131 | */
132 | async addTableIterator(tableName: string): Promise> {
133 | const emmiter = await this.addListener(tableName);
134 | return fromEmitter(emmiter, {
135 | onNext: "change",
136 | onError: "error",
137 | onDone: "close",
138 | });
139 | }
140 |
141 | /**
142 | * Remove a listener (or iterator) based on chain and tableId
143 | * @param params A TableIdentifier Object. Must have `chainId` and `tableId` keys.
144 | */
145 | removeListener(params: TableIdentifier): void {
146 | if (params == null) {
147 | throw new Error("must provide chainId and tableId to remove a listener");
148 | }
149 |
150 | const listenerId = `_${params.chainId}_${params.tableId}`;
151 | if (this.listeners[listenerId] == null) {
152 | throw new Error("cannot remove listener that does not exist");
153 | }
154 |
155 | const emitter = this.listeners[listenerId].emitter;
156 | emitter.removeAllListeners();
157 |
158 | // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
159 | delete this.listeners[listenerId];
160 | }
161 |
162 | // stop listening to the contract and remove all listeners
163 | removeAllListeners(): void {
164 | // Need to remove the contract listener first because removing
165 | // the table listener will delete the listeners object
166 | for (const chainId in this.contracts) {
167 | const contract = this.contracts[chainId];
168 | for (const listenerId in this.listeners) {
169 | const listenerObj = this.listeners[listenerId];
170 | const listenerObjChainId = listenerObj.chainId.toString();
171 |
172 | if (listenerObjChainId === chainId) {
173 | // If the chainId of the contract and the Listener Object are the same
174 | // then we want to dig into the Listener Object and for each event that
175 | // the contract is listening to we remove the listener
176 | for (let i = 0; i < listenerObj.contractListeners.length; i++) {
177 | const listenerEventFunc = listenerObj.contractListeners[i];
178 | contract.off(
179 | listenerEventFunc.eventName,
180 | listenerEventFunc.eventListener
181 | );
182 | }
183 | }
184 | }
185 | }
186 |
187 | // Now that the contract listeners are gone we can remove
188 | // the emitter listeners and delete the entries
189 | for (const listener in this.listeners) {
190 | const l = this.listeners[listener];
191 | this.removeListener({
192 | chainId: l.chainId,
193 | tableId: l.tableId,
194 | });
195 | }
196 | }
197 |
198 | async _getContract(chainId: number): Promise {
199 | if (this.contracts[chainId] != null) return this.contracts[chainId];
200 | if (this.config.signer == null) {
201 | /* c8 ignore next 2 */
202 | throw new Error("signer information is required to get contract");
203 | }
204 |
205 | const { contract } = await getContractAndOverrides(
206 | this.config.signer,
207 | chainId
208 | );
209 | this.contracts[chainId] = contract;
210 |
211 | return contract;
212 | }
213 |
214 | async _ensureListening(
215 | listenerId: string,
216 | emitter: EventEmitter
217 | ): Promise {
218 | const { chainId, tableId } = await getTableIdentifier(listenerId);
219 |
220 | const contract = await this._getContract(chainId);
221 | return this._attachEmitter(contract, emitter, { tableId, chainId });
222 | }
223 |
224 | _attachEmitter(
225 | contract: TablelandTables,
226 | emitter: EventEmitter,
227 | tableIdentifier: TableIdentifier
228 | ): ContractEventListener[] {
229 | const { tableId, chainId } = tableIdentifier;
230 | const listenerEventFunctions = [];
231 |
232 | for (const key in contractEvents) {
233 | const eve = contractEvents[key];
234 | // put the listener function in memory so we can remove it if needed
235 | const listener = (...args: any[]): void => {
236 | const _tableId = args[eve.tableIdIndex].toString();
237 | if (_tableId !== tableId) return;
238 | if (key !== "RunSQL") {
239 | emitter.emit(eve.emit, args);
240 | }
241 |
242 | const transactionHash = args[args.length - 1].transactionHash;
243 |
244 | const poll = async (): Promise => {
245 | const baseUrl =
246 | this.config.baseUrl == null
247 | ? await extractBaseUrl({ signer: this.config.signer })
248 | : this.config.baseUrl;
249 |
250 | const res = await pollTransactionReceipt(
251 | { baseUrl },
252 | { transactionHash, chainId }
253 | );
254 |
255 | emitter.emit("change", res);
256 | };
257 | poll().catch((err) => {
258 | /* c8 ignore next 1 */
259 | emitter.emit("error", { error: err, hash: transactionHash });
260 | });
261 | };
262 |
263 | contract.on(key, listener);
264 |
265 | listenerEventFunctions.push({
266 | eventName: key,
267 | eventListener: listener,
268 | });
269 | }
270 |
271 | return listenerEventFunctions;
272 | }
273 | }
274 |
--------------------------------------------------------------------------------
/LICENSE-APACHE:
--------------------------------------------------------------------------------
1 | Apache License
2 | Version 2.0, January 2004
3 | http://www.apache.org/licenses/
4 |
5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6 |
7 | 1. Definitions.
8 |
9 | "License" shall mean the terms and conditions for use, reproduction,
10 | and distribution as defined by Sections 1 through 9 of this document.
11 |
12 | "Licensor" shall mean the copyright owner or entity authorized by
13 | the copyright owner that is granting the License.
14 |
15 | "Legal Entity" shall mean the union of the acting entity and all
16 | other entities that control, are controlled by, or are under common
17 | control with that entity. For the purposes of this definition,
18 | "control" means (i) the power, direct or indirect, to cause the
19 | direction or management of such entity, whether by contract or
20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
21 | outstanding shares, or (iii) beneficial ownership of such entity.
22 |
23 | "You" (or "Your") shall mean an individual or Legal Entity
24 | exercising permissions granted by this License.
25 |
26 | "Source" form shall mean the preferred form for making modifications,
27 | including but not limited to software source code, documentation
28 | source, and configuration files.
29 |
30 | "Object" form shall mean any form resulting from mechanical
31 | transformation or translation of a Source form, including but
32 | not limited to compiled object code, generated documentation,
33 | and conversions to other media types.
34 |
35 | "Work" shall mean the work of authorship, whether in Source or
36 | Object form, made available under the License, as indicated by a
37 | copyright notice that is included in or attached to the work
38 | (an example is provided in the Appendix below).
39 |
40 | "Derivative Works" shall mean any work, whether in Source or Object
41 | form, that is based on (or derived from) the Work and for which the
42 | editorial revisions, annotations, elaborations, or other modifications
43 | represent, as a whole, an original work of authorship. For the purposes
44 | of this License, Derivative Works shall not include works that remain
45 | separable from, or merely link (or bind by name) to the interfaces of,
46 | the Work and Derivative Works thereof.
47 |
48 | "Contribution" shall mean any work of authorship, including
49 | the original version of the Work and any modifications or additions
50 | to that Work or Derivative Works thereof, that is intentionally
51 | submitted to Licensor for inclusion in the Work by the copyright owner
52 | or by an individual or Legal Entity authorized to submit on behalf of
53 | the copyright owner. For the purposes of this definition, "submitted"
54 | means any form of electronic, verbal, or written communication sent
55 | to the Licensor or its representatives, including but not limited to
56 | communication on electronic mailing lists, source code control systems,
57 | and issue tracking systems that are managed by, or on behalf of, the
58 | Licensor for the purpose of discussing and improving the Work, but
59 | excluding communication that is conspicuously marked or otherwise
60 | designated in writing by the copyright owner as "Not a Contribution."
61 |
62 | "Contributor" shall mean Licensor and any individual or Legal Entity
63 | on behalf of whom a Contribution has been received by Licensor and
64 | subsequently incorporated within the Work.
65 |
66 | 2. Grant of Copyright License. Subject to the terms and conditions of
67 | this License, each Contributor hereby grants to You a perpetual,
68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69 | copyright license to reproduce, prepare Derivative Works of,
70 | publicly display, publicly perform, sublicense, and distribute the
71 | Work and such Derivative Works in Source or Object form.
72 |
73 | 3. Grant of Patent License. Subject to the terms and conditions of
74 | this License, each Contributor hereby grants to You a perpetual,
75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76 | (except as stated in this section) patent license to make, have made,
77 | use, offer to sell, sell, import, and otherwise transfer the Work,
78 | where such license applies only to those patent claims licensable
79 | by such Contributor that are necessarily infringed by their
80 | Contribution(s) alone or by combination of their Contribution(s)
81 | with the Work to which such Contribution(s) was submitted. If You
82 | institute patent litigation against any entity (including a
83 | cross-claim or counterclaim in a lawsuit) alleging that the Work
84 | or a Contribution incorporated within the Work constitutes direct
85 | or contributory patent infringement, then any patent licenses
86 | granted to You under this License for that Work shall terminate
87 | as of the date such litigation is filed.
88 |
89 | 4. Redistribution. You may reproduce and distribute copies of the
90 | Work or Derivative Works thereof in any medium, with or without
91 | modifications, and in Source or Object form, provided that You
92 | meet the following conditions:
93 |
94 | (a) You must give any other recipients of the Work or
95 | Derivative Works a copy of this License; and
96 |
97 | (b) You must cause any modified files to carry prominent notices
98 | stating that You changed the files; and
99 |
100 | (c) You must retain, in the Source form of any Derivative Works
101 | that You distribute, all copyright, patent, trademark, and
102 | attribution notices from the Source form of the Work,
103 | excluding those notices that do not pertain to any part of
104 | the Derivative Works; and
105 |
106 | (d) If the Work includes a "NOTICE" text file as part of its
107 | distribution, then any Derivative Works that You distribute must
108 | include a readable copy of the attribution notices contained
109 | within such NOTICE file, excluding those notices that do not
110 | pertain to any part of the Derivative Works, in at least one
111 | of the following places: within a NOTICE text file distributed
112 | as part of the Derivative Works; within the Source form or
113 | documentation, if provided along with the Derivative Works; or,
114 | within a display generated by the Derivative Works, if and
115 | wherever such third-party notices normally appear. The contents
116 | of the NOTICE file are for informational purposes only and
117 | do not modify the License. You may add Your own attribution
118 | notices within Derivative Works that You distribute, alongside
119 | or as an addendum to the NOTICE text from the Work, provided
120 | that such additional attribution notices cannot be construed
121 | as modifying the License.
122 |
123 | You may add Your own copyright statement to Your modifications and
124 | may provide additional or different license terms and conditions
125 | for use, reproduction, or distribution of Your modifications, or
126 | for any such Derivative Works as a whole, provided Your use,
127 | reproduction, and distribution of the Work otherwise complies with
128 | the conditions stated in this License.
129 |
130 | 5. Submission of Contributions. Unless You explicitly state otherwise,
131 | any Contribution intentionally submitted for inclusion in the Work
132 | by You to the Licensor shall be under the terms and conditions of
133 | this License, without any additional terms or conditions.
134 | Notwithstanding the above, nothing herein shall supersede or modify
135 | the terms of any separate license agreement you may have executed
136 | with Licensor regarding such Contributions.
137 |
138 | 6. Trademarks. This License does not grant permission to use the trade
139 | names, trademarks, service marks, or product names of the Licensor,
140 | except as required for reasonable and customary use in describing the
141 | origin of the Work and reproducing the content of the NOTICE file.
142 |
143 | 7. Disclaimer of Warranty. Unless required by applicable law or
144 | agreed to in writing, Licensor provides the Work (and each
145 | Contributor provides its Contributions) on an "AS IS" BASIS,
146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 | implied, including, without limitation, any warranties or conditions
148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 | PARTICULAR PURPOSE. You are solely responsible for determining the
150 | appropriateness of using or redistributing the Work and assume any
151 | risks associated with Your exercise of permissions under this License.
152 |
153 | 8. Limitation of Liability. In no event and under no legal theory,
154 | whether in tort (including negligence), contract, or otherwise,
155 | unless required by applicable law (such as deliberate and grossly
156 | negligent acts) or agreed to in writing, shall any Contributor be
157 | liable to You for damages, including any direct, indirect, special,
158 | incidental, or consequential damages of any character arising as a
159 | result of this License or out of the use or inability to use the
160 | Work (including but not limited to damages for loss of goodwill,
161 | work stoppage, computer failure or malfunction, or any and all
162 | other commercial damages or losses), even if such Contributor
163 | has been advised of the possibility of such damages.
164 |
165 | 9. Accepting Warranty or Additional Liability. While redistributing
166 | the Work or Derivative Works thereof, You may choose to offer,
167 | and charge a fee for, acceptance of support, warranty, indemnity,
168 | or other liability obligations and/or rights consistent with this
169 | License. However, in accepting such obligations, You may act only
170 | on Your own behalf and on Your sole responsibility, not on behalf
171 | of any other Contributor, and only if You agree to indemnify,
172 | defend, and hold each Contributor harmless for any liability
173 | incurred by, or claims asserted against, such Contributor by reason
174 | of your accepting any such warranty or additional liability.
175 |
176 | END OF TERMS AND CONDITIONS
177 |
--------------------------------------------------------------------------------
/src/lowlevel.ts:
--------------------------------------------------------------------------------
1 | import {
2 | type Config,
3 | extractBaseUrl,
4 | extractSigner,
5 | normalize,
6 | type Signal,
7 | type ReadConfig,
8 | type NameMapping,
9 | } from "./helpers/index.js";
10 | import {
11 | prepareCreateOne,
12 | create,
13 | type CreateManyParams,
14 | } from "./registry/create.js";
15 | import {
16 | prepareMutateOne,
17 | mutate,
18 | type Runnable,
19 | type MutateManyParams,
20 | } from "./registry/run.js";
21 | import {
22 | type ExtractedStatement,
23 | type WaitableTransactionReceipt,
24 | wrapTransaction,
25 | wrapManyTransaction,
26 | } from "./registry/utils.js";
27 | import {
28 | type ObjectsFormat,
29 | type ValueOf,
30 | getQuery,
31 | } from "./validator/query.js";
32 | import { ApiError } from "./validator/index.js";
33 |
34 | // see `errorWithHint` for usage
35 | const hints = [
36 | {
37 | regexp: /syntax error at position \d+ near '.+'/,
38 | template: function (statement: string, match: any): string {
39 | const location = Number(match.input.slice(match.index).split(" ")[4]);
40 | if (isNaN(location)) return "";
41 |
42 | const termMatch = match.input.match(
43 | /syntax error at position \d+ (near '.+')/
44 | );
45 | if (
46 | termMatch == null ||
47 | termMatch.length < 1 ||
48 | termMatch[1].indexOf("near '") !== 0
49 | ) {
50 | return "";
51 | }
52 |
53 | // isolate the term from the matched string
54 | const term = termMatch[1].slice(6, -1);
55 |
56 | const padding = " ".repeat(location - term.length);
57 | const carrots = "^".repeat(term.length);
58 |
59 | return `${statement}
60 | ${padding}${carrots}`;
61 | },
62 | },
63 | {
64 | regexp: /no such column/,
65 | template: function (statement: string, match: any): string {
66 | // note: the error returned from the validator, and the one generated in the client
67 | // in the client already include the name of the column.
68 | return statement;
69 | },
70 | },
71 | ];
72 |
73 | // TODO: this only works if the transaction will only be affecting a single table.
74 | // I've currently got new versions of this below called execMutateMany and
75 | // execCreateMany, but we might be able to combine all of these `exec` functions
76 | // into one when we move to version 5.
77 | export async function exec(
78 | config: Config,
79 | { type, sql, tables: [first] }: ExtractedStatement
80 | ): Promise {
81 | const signer = await extractSigner(config);
82 | const chainId = await signer.getChainId();
83 | const baseUrl = await extractBaseUrl(config, chainId);
84 | const _config = { baseUrl, signer };
85 | const _params = { chainId, first, statement: sql };
86 | switch (type) {
87 | case "create": {
88 | if (typeof config.aliases?.read === "function") {
89 | const currentAliases = await config.aliases.read();
90 | if (currentAliases[first] != null) {
91 | throw new Error("table name already exists in aliases");
92 | }
93 | }
94 |
95 | const { prefix, ...prepared } = await prepareCreateOne(_params);
96 | const tx = await create(_config, prepared);
97 | const wrappedTx = await wrapTransaction(_config, prefix, tx);
98 |
99 | if (typeof config.aliases?.write === "function") {
100 | const uuTableName = wrappedTx.name;
101 | const nameMap: NameMapping = {};
102 | nameMap[first] = uuTableName;
103 |
104 | await config.aliases.write(nameMap);
105 | }
106 |
107 | return wrappedTx;
108 | }
109 | /* c8 ignore next */
110 | case "acl":
111 | case "write": {
112 | if (typeof config.aliases?.read === "function") {
113 | const nameMap = await config.aliases.read();
114 | const norm = await normalize(_params.statement, nameMap);
115 |
116 | _params.statement = norm.statements[0];
117 | _params.first = nameMap[first] != null ? nameMap[first] : first;
118 | }
119 |
120 | const { prefix, ...prepared } = await prepareMutateOne(_params);
121 | const tx = await mutate(_config, prepared);
122 | return await wrapTransaction(_config, prefix, tx);
123 | }
124 | /* c8 ignore next 2 */
125 | default:
126 | throw new Error("invalid statement type: read");
127 | }
128 | }
129 |
130 | /**
131 | * This is an internal method that will call the Registry Contract `mutate` method
132 | * with a set of Runnables.
133 | * Once the contract call finishes, this returns the mapping of the contract tx results
134 | * to the Runnables argument.
135 | */
136 | export async function execMutateMany(
137 | config: Config,
138 | runnables: Runnable[]
139 | ): Promise {
140 | const signer = await extractSigner(config);
141 | const chainId = await signer.getChainId();
142 | const baseUrl = await extractBaseUrl(config, chainId);
143 | const _config = { baseUrl, signer };
144 | const params: MutateManyParams = { runnables, chainId };
145 |
146 | if (typeof config.aliases?.read === "function") {
147 | const nameMap = await config.aliases.read();
148 |
149 | params.runnables = await Promise.all(
150 | params.runnables.map(async function (runnable) {
151 | const norm = await normalize(runnable.statement, nameMap);
152 | runnable.statement = norm.statements[0];
153 |
154 | return runnable;
155 | })
156 | );
157 | }
158 |
159 | const tx = await mutate(_config, params);
160 |
161 | return await wrapManyTransaction(
162 | _config,
163 | runnables.map((r) => r.statement),
164 | tx
165 | );
166 | }
167 |
168 | /**
169 | * This is an internal method that will call the Registry Contract `create` method with
170 | * a set of sql create statements.
171 | * Once the contract call finishes, this returns the mapping of the contract tx results to
172 | * the create statements.
173 | */
174 | export async function execCreateMany(
175 | config: Config,
176 | statements: string[]
177 | ): Promise {
178 | const signer = await extractSigner(config);
179 | const chainId = await signer.getChainId();
180 | const baseUrl = await extractBaseUrl(config, chainId);
181 | const _config = { baseUrl, signer };
182 | const params: CreateManyParams = {
183 | statements: await Promise.all(
184 | statements.map(async function (statement) {
185 | const prepared = await prepareCreateOne({ statement, chainId });
186 | return prepared.statement;
187 | })
188 | ),
189 | chainId,
190 | };
191 |
192 | const tx = await create(_config, params);
193 | const wrappedTx = await wrapManyTransaction(_config, statements, tx);
194 |
195 | if (typeof config.aliases?.write === "function") {
196 | const currentAliases = await config.aliases.read();
197 |
198 | // Collect the user provided table names to add to the aliases.
199 | const aliasesTableNames = await Promise.all(
200 | statements.map(async function (statement) {
201 | const norm = await normalize(statement);
202 | if (currentAliases[norm.tables[0]] != null) {
203 | throw new Error("table name already exists in aliases");
204 | }
205 | return norm.tables[0];
206 | })
207 | );
208 |
209 | const uuTableNames = wrappedTx.names;
210 | const nameMap: NameMapping = {};
211 | for (let i = 0; i < aliasesTableNames.length; i++) {
212 | nameMap[aliasesTableNames[i]] = uuTableNames[i];
213 | }
214 |
215 | await config.aliases.write(nameMap);
216 | }
217 | return wrappedTx;
218 | }
219 |
220 | export function errorWithCause(code: string, cause: Error): Error {
221 | return new Error(`${code}: ${cause.message}`, { cause });
222 | }
223 |
224 | export function errorWithHint(statement: string, cause: Error): Error {
225 | if (cause.message == null || statement == null) return cause;
226 |
227 | let errorMessage = cause.message;
228 | try {
229 | for (let i = 0; i < hints.length; i++) {
230 | const hint = hints[i];
231 | const match = errorMessage.match(hint.regexp);
232 | if (match == null) continue;
233 |
234 | const hintMessage = hint.template(statement, match);
235 | errorMessage += hintMessage !== "" ? `\n${hintMessage}` : "";
236 | break;
237 | }
238 |
239 | return new Error(errorMessage, { cause });
240 | } catch (err) {
241 | return cause;
242 | }
243 | }
244 |
245 | function catchNotFound(err: unknown): [] {
246 | if (err instanceof ApiError && err.status === 404) {
247 | return [];
248 | }
249 | throw err;
250 | }
251 |
252 | export async function queryRaw(
253 | config: ReadConfig,
254 | statement: string,
255 | opts: Signal = {}
256 | ): Promise>> {
257 | const params = { statement, format: "table" } as const;
258 | const response = await getQuery(config, params, opts)
259 | .then((res) => res.rows)
260 | .catch(catchNotFound);
261 | return response;
262 | }
263 |
264 | export async function queryAll(
265 | config: ReadConfig,
266 | statement: string,
267 | opts: Signal = {}
268 | ): Promise> {
269 | const params = { statement, format: "objects" } as const;
270 | const response = await getQuery(config, params, opts).catch(catchNotFound);
271 | return response;
272 | }
273 |
274 | export async function queryFirst(
275 | config: ReadConfig,
276 | statement: string,
277 | opts: Signal = {}
278 | ): Promise {
279 | const response = await queryAll(config, statement, opts).catch(
280 | catchNotFound
281 | );
282 | return response.shift() ?? null;
283 | }
284 |
285 | export function extractColumn(
286 | values: T,
287 | colName: K
288 | ): T[K];
289 | export function extractColumn(
290 | values: T[],
291 | colName: K
292 | ): Array;
293 | export function extractColumn(
294 | values: T[] | T,
295 | colName: K
296 | ): Array