Skip to content

Commit 0abea55

Browse files
ponderingdemocritusponderingdemocritus
committed
feat: docs
1 parent eb0fc22 commit 0abea55

File tree

10 files changed

+290
-89
lines changed

10 files changed

+290
-89
lines changed

‎examples/clients/react/react-sdk/src/App.tsx

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ function App() {
2222
const subscription = await db.subscribeEntityQuery(
2323
{
2424
dojo_starter: {
25-
Position: true,
26-
Moves: true,
25+
Position: [],
26+
// Moves: ["player"],
2727
},
2828
},
2929
(response) => {
@@ -124,8 +124,6 @@ function App() {
124124
</p>
125125
<h3>Moves</h3>
126126
<p>
127-
Player:{" "}
128-
{entity.models.dojo_starter.Moves?.player ?? "N/A"}
129127
<br />
130128
Can Move:{" "}
131129
{entity.models.dojo_starter.Moves?.can_move?.toString() ??

‎examples/clients/react/react-sdk/src/bindings.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,5 +35,6 @@ type Schema = {
3535
Position: Position;
3636
};
3737
};
38+
3839
export type { Schema, Moves, DirectionsAvailable, Position, Vec2 };
3940
export { Direction };

‎packages/sdk/src/__tests__/convertQueryToEntityKeyClauses.test.ts

Lines changed: 6 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -69,14 +69,14 @@ describe("convertQueryToEntityKeyClauses", () => {
6969
it("should convert query with namespace and model keys array to FixedLen Keys clause", () => {
7070
const query: SubscriptionQueryType<MockSchemaType> = {
7171
world: {
72-
item: ["key1", "key2"],
72+
item: ["id", "type"],
7373
},
7474
};
7575
const result = convertQueryToEntityKeyClauses(query);
7676
const expected: torii.EntityKeysClause[] = [
7777
{
7878
Keys: {
79-
keys: ["key1", "key2"],
79+
keys: ["id", "type"],
8080
pattern_matching: "FixedLen",
8181
models: ["world-item"],
8282
},
@@ -89,7 +89,7 @@ describe("convertQueryToEntityKeyClauses", () => {
8989
const query: SubscriptionQueryType<MockSchemaType> = {
9090
world: {
9191
player: true,
92-
item: ["keyA", "keyB"],
92+
item: ["id", "type"],
9393
},
9494
entityIds: ["hash1"],
9595
} as unknown as SubscriptionQueryType<MockSchemaType>;
@@ -105,29 +105,7 @@ describe("convertQueryToEntityKeyClauses", () => {
105105
},
106106
{
107107
Keys: {
108-
keys: ["keyA", "keyB"],
109-
pattern_matching: "FixedLen",
110-
models: ["world-item"],
111-
},
112-
},
113-
];
114-
expect(result).toEqual(expected);
115-
});
116-
117-
it("should ignore non-object entries except entityIds", () => {
118-
const query = {
119-
world: {
120-
player: "invalid",
121-
item: ["key1"],
122-
},
123-
entityIds: ["hash1"],
124-
} as unknown as SubscriptionQueryType<MockSchemaType>;
125-
const result = convertQueryToEntityKeyClauses(query);
126-
const expected: torii.EntityKeysClause[] = [
127-
{ HashedKeys: ["hash1"] },
128-
{
129-
Keys: {
130-
keys: ["key1"],
108+
keys: ["id", "type"],
131109
pattern_matching: "FixedLen",
132110
models: ["world-item"],
133111
},
@@ -160,7 +138,7 @@ describe("convertQueryToEntityKeyClauses", () => {
160138
const query: SubscriptionQueryType<MockSchemaType> = {
161139
world: {
162140
player: true,
163-
item: ["keyX", "keyY"],
141+
item: ["id", "type"],
164142
},
165143
};
166144
const result = convertQueryToEntityKeyClauses(query);
@@ -174,7 +152,7 @@ describe("convertQueryToEntityKeyClauses", () => {
174152
},
175153
{
176154
Keys: {
177-
keys: ["keyX", "keyY"],
155+
keys: ["id", "type"],
178156
pattern_matching: "FixedLen",
179157
models: ["world-item"],
180158
},

‎packages/sdk/src/convertQuerytoClause.ts

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,29 @@
11
import * as torii from "@dojoengine/torii-client";
22
import { SchemaType, QueryType } from "./types";
33

4+
/**
5+
* Converts a query object into a Torii clause.
6+
*
7+
* @template T - The schema type.
8+
* @param {QueryType<T>} query - The query object to convert.
9+
* @param {torii.LogicalOperator} [operator="And"] - The logical operator to combine clauses. Default is "And".
10+
* @returns {torii.Clause} - The resulting Torii clause.
11+
*
12+
* @example
13+
* const query = {
14+
* users: {
15+
* age: {
16+
* $: {
17+
* where: {
18+
* $gt: 18
19+
* }
20+
* }
21+
* }
22+
* }
23+
* };
24+
* const clause = convertQueryToClause(query);
25+
* console.log(clause);
26+
*/
427
export function convertQueryToClause<T extends SchemaType>(
528
query: QueryType<T>,
629
operator: torii.LogicalOperator = "And"
@@ -95,7 +118,17 @@ export function convertQueryToClause<T extends SchemaType>(
95118
};
96119
}
97120

98-
// TODO: we could expand on these
121+
/**
122+
* Converts a value to a Torii primitive type.
123+
*
124+
* @param {any} value - The value to convert.
125+
* @returns {torii.MemberValue} - The converted primitive value.
126+
* @throws {Error} - If the value type is unsupported.
127+
*
128+
* @example
129+
* const primitiveValue = convertToPrimitive(42);
130+
* console.log(primitiveValue); // { Primitive: { U32: 42 } }
131+
*/
99132
function convertToPrimitive(value: any): torii.MemberValue {
100133
if (typeof value === "number") {
101134
return { Primitive: { U32: value } };
@@ -115,6 +148,17 @@ function convertToPrimitive(value: any): torii.MemberValue {
115148
throw new Error(`Unsupported primitive type: ${typeof value}`);
116149
}
117150

151+
/**
152+
* Converts a query operator to a Torii comparison operator.
153+
*
154+
* @param {string} operator - The query operator to convert.
155+
* @returns {torii.ComparisonOperator} - The corresponding Torii comparison operator.
156+
* @throws {Error} - If the operator is unsupported.
157+
*
158+
* @example
159+
* const comparisonOperator = convertOperator("$eq");
160+
* console.log(comparisonOperator); // "Eq"
161+
*/
118162
function convertOperator(operator: string): torii.ComparisonOperator {
119163
switch (operator) {
120164
case "$eq":

‎packages/sdk/src/getEntities.ts

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,28 @@ import { parseEntities } from "./parseEntities";
44
import { SchemaType } from "./types";
55
import * as torii from "@dojoengine/torii-client";
66

7+
/**
8+
* Fetches entities from the Torii client based on the provided query.
9+
*
10+
* @template T - The schema type.
11+
* @param {torii.ToriiClient} client - The Torii client instance used to fetch entities.
12+
* @param {QueryType<T>} query - The query object used to filter entities.
13+
* @param {(response: { data?: StandardizedQueryResult<T>; error?: Error }) => void} callback - The callback function to handle the response.
14+
* @param {number} [limit=100] - The maximum number of entities to fetch per request. Default is 100.
15+
* @param {number} [offset=0] - The offset to start fetching entities from. Default is 0.
16+
* @param {{ logging?: boolean }} [options] - Optional settings.
17+
* @param {boolean} [options.logging] - If true, enables logging of the fetching process. Default is false.
18+
* @returns {Promise<StandardizedQueryResult<T>>} - A promise that resolves to the standardized query result.
19+
*
20+
* @example
21+
* const result = await getEntities(client, query, (response) => {
22+
* if (response.error) {
23+
* console.error("Error:", response.error);
24+
* } else {
25+
* console.log("Data:", response.data);
26+
* }
27+
* }, 100, 0, { logging: true });
28+
*/
729
export async function getEntities<T extends SchemaType>(
830
client: torii.ToriiClient,
931
query: QueryType<T>,

‎packages/sdk/src/getEventMessages.ts

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,33 @@
1-
import { QueryResult, QueryType } from "./types";
1+
import { StandardizedQueryResult, QueryType } from "./types";
22
import { convertQueryToClause } from "./convertQuerytoClause";
33
import { parseEntities } from "./parseEntities";
44
import { SchemaType } from "./types";
55
import * as torii from "@dojoengine/torii-client";
66

7+
/**
8+
* Fetches event messages from the Torii client based on the provided query.
9+
*
10+
* @template T - The schema type.
11+
* @param {torii.ToriiClient} client - The Torii client instance used to fetch event messages.
12+
* @param {QueryType<T>} query - The query object used to filter event messages.
13+
* @param {(response: { data?: StandardizedQueryResult<T>; error?: Error }) => void} callback - The callback function to handle the response.
14+
* @param {number} [limit=100] - The maximum number of event messages to fetch per request. Default is 100.
15+
* @param {number} [offset=0] - The offset to start fetching event messages from. Default is 0.
16+
* @param {{ logging?: boolean }} [options] - Optional settings.
17+
* @param {boolean} [options.logging] - If true, enables logging of the fetching process. Default is false.
18+
* @returns {Promise<StandardizedQueryResult<T>>} - A promise that resolves to the standardized query result.
19+
*/
720
export async function getEventMessages<T extends SchemaType>(
821
client: torii.ToriiClient,
922
query: QueryType<T>,
10-
callback: (response: { data?: QueryResult<T>; error?: Error }) => void,
23+
callback: (response: {
24+
data?: StandardizedQueryResult<T>;
25+
error?: Error;
26+
}) => void,
1127
limit: number = 100, // Default limit
1228
offset: number = 0, // Default offset
1329
options?: { logging?: boolean } // Logging option
14-
): Promise<QueryResult<T>> {
30+
): Promise<StandardizedQueryResult<T>> {
1531
const clause = convertQueryToClause(query);
1632

1733
console.log(clause);
@@ -39,7 +55,7 @@ export async function getEventMessages<T extends SchemaType>(
3955

4056
Object.assign(allEntities, entities);
4157

42-
const parsedEntities = parseEntities<T>(allEntities, query);
58+
const parsedEntities = parseEntities<T>(allEntities);
4359

4460
console.log("parsedEntities", parsedEntities);
4561

@@ -62,5 +78,5 @@ export async function getEventMessages<T extends SchemaType>(
6278
if (options?.logging) {
6379
console.log("All fetched entities:", allEntities);
6480
}
65-
return parseEntities<T>(allEntities, query);
81+
return parseEntities<T>(allEntities);
6682
}

‎packages/sdk/src/index.ts

Lines changed: 5 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,23 @@
11
import * as torii from "@dojoengine/torii-client";
2-
import {
3-
StandardizedQueryResult,
4-
QueryType,
5-
SchemaType,
6-
SubscriptionQueryType,
7-
} from "./types";
2+
import { SchemaType, SDK } from "./types";
83
import { subscribeEntityQuery } from "./subscribeEntityQuery";
94
import { getEntities } from "./getEntities";
105

116
export * from "./types";
127

138
import { subscribeEventQuery } from "./subscribeEventQuery";
9+
import { getEventMessages } from "./getEventMessages";
1410

1511
async function createClient(
1612
config: torii.ClientConfig
1713
): Promise<torii.ToriiClient> {
1814
return await torii.createClient(config);
1915
}
2016

21-
export async function init<
22-
T extends SchemaType,
23-
// U extends readonly ContractDefinition[],
24-
>(
17+
export async function init<T extends SchemaType>(
2518
options: torii.ClientConfig
26-
// worldContracts: U,
27-
// account: AccountInterface
28-
): Promise<{
29-
client: torii.ToriiClient;
30-
subscribeEntityQuery: (
31-
query: SubscriptionQueryType<T>,
32-
callback: (response: {
33-
data?: StandardizedQueryResult<T>;
34-
error?: Error;
35-
}) => void
36-
) => Promise<torii.Subscription>;
37-
subscribeEventQuery: (
38-
query: SubscriptionQueryType<T>,
39-
callback: (response: {
40-
data?: StandardizedQueryResult<T>;
41-
error?: Error;
42-
}) => void
43-
) => Promise<torii.Subscription>;
44-
getEntities: (
45-
query: QueryType<T>,
46-
callback: (response: {
47-
data?: StandardizedQueryResult<T>;
48-
error?: Error;
49-
}) => void
50-
) => Promise<StandardizedQueryResult<T>>;
51-
getEventMessages: (
52-
query: QueryType<T>,
53-
callback: (response: {
54-
data?: StandardizedQueryResult<T>;
55-
error?: Error;
56-
}) => void
57-
) => Promise<StandardizedQueryResult<T>>;
58-
// worldProxy: WorldContracts<U>;
59-
}> {
19+
): Promise<SDK<T>> {
6020
const client = await createClient(options);
61-
// const worldProxy = createWorldProxy(worldContracts, account);
6221

6322
return {
6423
client,
@@ -68,8 +27,7 @@ export async function init<
6827
subscribeEventQuery(client, query, callback),
6928
getEntities: (query, callback) => getEntities(client, query, callback),
7029
getEventMessages: (query, callback) =>
71-
getEntities(client, query, callback),
72-
// worldProxy,
30+
getEventMessages(client, query, callback),
7331
};
7432
}
7533
// // EXAMPLE FOR NOW

‎packages/sdk/src/subscribeEntityQuery.ts

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,25 @@ import {
77
} from "./types";
88
import { parseEntities } from "./parseEntities";
99

10+
/**
11+
* Subscribes to entity updates based on the provided query and invokes the callback with the updated data.
12+
*
13+
* @template T - The schema type.
14+
* @param {torii.ToriiClient} client - The Torii client instance.
15+
* @param {SubscriptionQueryType<T>} [query] - The subscription query to filter the entities.
16+
* @param {(response: { data?: StandardizedQueryResult<T>; error?: Error }) => void} [callback] - The callback function to handle the response.
17+
* @param {{ logging?: boolean }} [options] - Optional settings for the subscription.
18+
* @returns {Promise<torii.Subscription>} - A promise that resolves to a Torii subscription.
19+
*
20+
* @example
21+
* const subscription = await subscribeEntityQuery(client, query, (response) => {
22+
* if (response.error) {
23+
* console.error("Error:", response.error);
24+
* } else {
25+
* console.log("Data:", response.data);
26+
* }
27+
* }, { logging: true });
28+
*/
1029
export async function subscribeEntityQuery<T extends SchemaType>(
1130
client: torii.ToriiClient,
1231
query?: SubscriptionQueryType<T>,
@@ -16,6 +35,10 @@ export async function subscribeEntityQuery<T extends SchemaType>(
1635
}) => void,
1736
options?: { logging?: boolean }
1837
): Promise<torii.Subscription> {
38+
console.log(
39+
"convertQueryToEntityKeyClauses",
40+
convertQueryToEntityKeyClauses(query)
41+
);
1942
return client.onEntityUpdated(
2043
convertQueryToEntityKeyClauses(query),
2144
(entityId: string, entityData: any) => {

‎packages/sdk/src/subscribeEventQuery.ts

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,25 @@ import {
77
} from "./types";
88
import { parseEntities } from "./parseEntities";
99

10+
/**
11+
* Subscribes to event messages based on the provided query and invokes the callback with the updated data.
12+
*
13+
* @template T - The schema type.
14+
* @param {torii.ToriiClient} client - The Torii client instance.
15+
* @param {SubscriptionQueryType<T>} [query] - The subscription query to filter the events.
16+
* @param {(response: { data?: StandardizedQueryResult<T>; error?: Error }) => void} [callback] - The callback function to handle the response.
17+
* @param {{ logging?: boolean }} [options] - Optional settings for the subscription.
18+
* @returns {Promise<torii.Subscription>} - A promise that resolves to a Torii subscription.
19+
*
20+
* @example
21+
* const subscription = await subscribeEventQuery(client, query, (response) => {
22+
* if (response.error) {
23+
* console.error("Error:", response.error);
24+
* } else {
25+
* console.log("Data:", response.data);
26+
* }
27+
* }, { logging: true });
28+
*/
1029
export async function subscribeEventQuery<T extends SchemaType>(
1130
client: torii.ToriiClient,
1231
query?: SubscriptionQueryType<T>,

0 commit comments

Comments
 (0)