Skip to content

Commit dc53b30

Browse files
jaswinder6991jaswinder6991
authored
feat: adding api server support for read methods (#33)
* feat: adding api server support for read methods * feat(wip): added more args to get and introduced keys method * chore: fixed merge issues * feat: added index() function and docs for all api server changes * docs: fix docs build
1 parent 7228ba4 commit dc53b30

21 files changed

+846
-22
lines changed

‎docs/advanced/fetching-indexed-data.mdx

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
import TOCInline from '@theme/TOCInline';
4+
5+
# Fetching Indexed Data
6+
7+
## Overview
8+
9+
The `index` function in the Social SDK allows you to retrieve indexed values based on specified criteria from the Social API server. This function is crucial for efficient lookups of social interactions or custom indexed data, supporting various filtering, ordering, and pagination options.
10+
11+
:::note
12+
13+
The `index` function is only available through the API server and does not have an RPC version.
14+
15+
:::
16+
17+
## Function Signature
18+
19+
```typescript
20+
public async index({
21+
action,
22+
key,
23+
accountId,
24+
order,
25+
limit,
26+
from,
27+
}: IIndexOptions): Promise<Record<string, unknown>>
28+
```
29+
30+
### Parameters
31+
32+
- `action`: The index_type from the standard (e.g., 'like' in the path 'index/like').
33+
- `key`: Can be either a string or an object:
34+
- If string: The inner indexed value from the standard.
35+
- If object: Can include properties like type, path, and blockHeight.
36+
- `accountId` (optional): A string or array of account IDs to filter values.
37+
- `order` (optional): The order of results. Either 'asc' or 'desc'. Default is 'asc'.
38+
- `limit` (optional): The number of values to return. Default is 100.
39+
- `from` (optional): The starting point for fetching results. Defaults to 0 or Max depending on order.
40+
41+
### Return Value
42+
43+
A promise that resolves to an array of matched indexed values, ordered by blockHeight.
44+
45+
## Usage Examples
46+
47+
### Basic Usage
48+
49+
<Tabs
50+
defaultValue="javascript-via-package-manager"
51+
values={[
52+
{ label: 'JavaScript (via package manager)', value: 'javascript-via-package-manager' },
53+
{ label: 'JavaScript (via CDN)', value: 'javascript-via-cdn' },
54+
{ label: 'TypeScript', value: 'typescript' },
55+
]}>
56+
<TabItem value="javascript-via-package-manager">
57+
58+
```js
59+
const { Social } = require('@builddao/near-social-js');
60+
61+
const social = new Social();
62+
const result = await social.index({
63+
action: 'like',
64+
key: 'post-123',
65+
});
66+
67+
console.log(result);
68+
```
69+
70+
</TabItem>
71+
<TabItem value="javascript-via-cdn">
72+
73+
```js
74+
var social = new NEARSocialSDK();
75+
76+
social.index({
77+
action: 'like',
78+
key: 'post-123',
79+
}).then((result) => {
80+
console.log(result);
81+
});
82+
```
83+
84+
</TabItem>
85+
<TabItem value="typescript">
86+
87+
```typescript
88+
import { Social } from '@builddao/near-social-js';
89+
90+
const social = new Social();
91+
const result = await social.index({
92+
action: 'like',
93+
key: 'post-123',
94+
});
95+
96+
console.log(result);
97+
```
98+
99+
</TabItem>
100+
</Tabs>
101+
102+
### Advanced Usage
103+
104+
You can use additional options to customize the behavior of the `index` function:
105+
106+
```typescript
107+
const result = await social.index({
108+
action: 'follow',
109+
key: 'alice.near',
110+
accountId: ['bob.near', 'charlie.near'],
111+
order: 'desc',
112+
limit: '50',
113+
from: 100,
114+
});
115+
```
116+
117+
This example retrieves the last 50 'follow' actions for 'alice.near', starting from the 100th most recent entry, and only includes actions by 'bob.near' and 'charlie.near'.
118+
119+
## Use Cases
120+
121+
The `index` function is particularly useful for:
122+
123+
1. Fetching all 'like' actions for a specific post:
124+
```typescript
125+
const likes = await social.index({
126+
action: 'like',
127+
key: {
128+
type: 'social',
129+
path: 'efiz.near/post/main',
130+
blockHeight: 124692995,//blockHeight of the post
131+
},
132+
});
133+
```
134+
135+
2. Retrieving recent 'follow' actions for a user:
136+
```typescript
137+
const result = await social.index({
138+
action: 'graph',
139+
key: 'follow',
140+
order: 'desc',
141+
accountId: 'alice.near',
142+
limit: '10',
143+
});
144+
```
145+
146+
3. Querying custom indexed data based on application-specific schemas:
147+
```typescript
148+
const customData = await social.index({
149+
action: 'custom-action',
150+
key: 'app-specific-key',
151+
});
152+
```
153+
154+
By leveraging the `index` function, you can build efficient and scalable features in your NEAR Social applications, such as activity feeds, trending content algorithms, or custom data aggregations.
155+
156+
:::tip
157+
158+
Combine the `index` function with `get` and `keys` for comprehensive data retrieval strategies in your application.
159+
160+
:::

‎docs/advanced/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Advanced
22

33
* [Reading Data](advanced/reading-data)
4+
* [Fetching Indexed Data](advanced/fetching-indexed-data)
45
* [Storing Data](advanced/storing-data)
56
* [Granting Write Permission](advanced/granting-write-permission)
67
* [Storage Deposit/Withdrawal](advanced/storage-deposit-withdraw)

‎docs/advanced/reading-data.mdx

Lines changed: 138 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,18 @@ import TOCInline from '@theme/TOCInline';
44

55
# Reading Data
66

7+
The Social SDK provides two main functions for reading data: `get` and `keys`. Both functions now support API server requests for improved performance on mainnet, as well as direct contract calls.
8+
79
<TOCInline
810
maxHeadingLevel={4}
911
toc={toc}
1012
/>
1113

14+
# Get Function
15+
1216
## Overview
1317

14-
Reading data is referenced by a set of key paths, where each path corresponds to the object to return.
18+
The get function in the Social SDK allows you to read data referenced by a set of key paths, where each path corresponds to the object to return. This function now supports both direct contract calls and API server requests for improved performance on mainnet.
1519

1620
:::note
1721

@@ -257,3 +261,136 @@ The [`get`](../api-reference/social#getoptions) function also supports wildcard
257261

258262
</TabItem>
259263
</Tabs>
264+
265+
## Using API Server (Default)
266+
By default, the get function uses the API server for improved performance on mainnet. You don't need to specify any additional parameters for this behavior.
267+
This is only for mainnet.
268+
269+
270+
## Using Direct Contract Calls
271+
If you want to make direct contract calls instead of using the API server, you can set useApiServer to false:
272+
```typescript
273+
const result = await social.get({
274+
keys: ['alice.near/profile/**'],
275+
useApiServer: false,
276+
});
277+
```
278+
Note that when using direct contract calls, you can use the withNodeId option, which is not available when using the API server.
279+
280+
281+
# Keys Function
282+
283+
## Overview
284+
285+
The `keys` function allows you to retrieve a list of keys that match specified criteria. This is useful for querying the data structure without necessarily reading all the associated values.
286+
287+
## Usage Examples
288+
289+
### Basic Usage
290+
291+
<Tabs
292+
defaultValue="javascript-via-package-manager"
293+
values={[
294+
{ label: 'JavaScript (via package manager)', value: 'javascript-via-package-manager' },
295+
{ label: 'JavaScript (via CDN)', value: 'javascript-via-cdn' },
296+
{ label: 'TypeScript', value: 'typescript' },
297+
]}>
298+
<TabItem value="javascript-via-package-manager">
299+
300+
```js
301+
const { Social } = require('@builddao/near-social-js');
302+
303+
const social = new Social();
304+
const result = await social.keys({
305+
keys: [
306+
'alice.near/profile/**',
307+
'bob.near/post/**',
308+
],
309+
});
310+
311+
console.log(result);
312+
```
313+
314+
</TabItem>
315+
<TabItem value="javascript-via-cdn">
316+
317+
```js
318+
var social = new NEARSocialSDK();
319+
320+
social.keys({
321+
keys: [
322+
'alice.near/profile/**',
323+
'bob.near/post/**',
324+
],
325+
}).then((result) => {
326+
console.log(result);
327+
});
328+
```
329+
330+
</TabItem>
331+
<TabItem value="typescript">
332+
333+
```typescript
334+
import { Social } from '@builddao/near-social-js';
335+
336+
const social = new Social();
337+
const result = await social.keys({
338+
keys: [
339+
'alice.near/profile/**',
340+
'bob.near/post/**',
341+
],
342+
});
343+
344+
console.log(result);
345+
```
346+
347+
</TabItem>
348+
</Tabs>
349+
350+
### Using API Server (Default)
351+
352+
By default, the `keys` function uses the API server for improved performance on mainnet. You don't need to specify any additional parameters for this behavior.
353+
354+
### Using Direct Contract Calls
355+
356+
If you want to make direct contract calls instead of using the API server, you can set `useApiServer` to `false`:
357+
358+
```typescript
359+
const result = await social.keys({
360+
keys: ['alice.near/profile/**'],
361+
useApiServer: false,
362+
});
363+
```
364+
365+
### Additional Options
366+
367+
You can use additional options to customize the behavior of the `keys` function:
368+
369+
```typescript
370+
const result = await social.keys({
371+
keys: ['alice.near/profile/**'],
372+
blockHeight: 12345678,
373+
returnDeleted: true,
374+
returnType: 'History',
375+
valuesOnly: true,
376+
});
377+
```
378+
379+
This example retrieves keys at a specific block height, includes deleted keys, returns historical data, and only includes values in the response.
380+
381+
:::note
382+
383+
The `returnType` option with value "History" is only supported when using the API server (`useApiServer: true`).
384+
385+
:::
386+
387+
## Use Cases
388+
389+
The `keys` function is particularly useful for:
390+
391+
1. Discovering available data structures without fetching all the associated values.
392+
2. Checking for the existence of certain keys or patterns in the data.
393+
3. Retrieving metadata about keys, such as when they were last updated or deleted.
394+
4. Efficiently querying large data sets by first fetching keys and then selectively retrieving values.
395+
396+
By combining the `get` and `keys` functions, you can build powerful and efficient data retrieval strategies for your NEAR Social applications.

‎docs/api-reference/social.mdx

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,14 +41,50 @@ import TOCInline from '@theme/TOCInline';
4141

4242
| Name | Type | Required | Default | Description |
4343
|---------|------------------------------------|----------|---------|-----------------------------------------------------|
44-
| options | [`IGetOptions`](types#igetoptions) | yes | - | Options that include the rpc url and a set of keys. |
44+
| options | [`IGetOptions`](types#igetoptions) | yes | - | Options that include the set of keys. |
4545

4646
#### Returns
4747

4848
| Type | Description |
4949
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
5050
| `Promise<object>` | A promise that resolves to an object with the top-level properties referencing the keys and the nested properties/objects referencing the corresponding path. |
5151

52+
### `keys(options)`
53+
> Retrieves a list of keys that match specified criteria.
54+
> This function is useful for querying the data structure without necessarily reading all the associated values.
55+
> For example:
56+
> * `alice.near/profile/**` - will match all keys under the profile of account `alice.near`.
57+
> * `*/post/*` - will match all post keys for all accounts.
58+
> * `bob.near/widget/***` - will match all widget keys and their nested keys for account `bob.near`.
59+
60+
#### Parameters
61+
| Name | Type | Required | Default | Description |
62+
|---------|--------------------------------------|----------|---------|-----------------------------------------------------|
63+
| options | [`IKeysOptions`](types#ikeysoptions) | yes | - | Options that specify the criteria for key retrieval. |
64+
65+
#### Returns
66+
| Type | Description |
67+
|-------------------|---------------------------------------------------------------------------------------------------------------|
68+
| `Promise<object>` | A promise that resolves to an object containing the matching keys and their metadata, ordered by block height. |
69+
70+
### `index(options)`
71+
> Retrieves indexed values based on specified criteria from the Social API server.
72+
> This function is crucial for efficient lookups of social interactions or custom indexed data.
73+
> For example:
74+
> * Fetching all 'like' actions for a specific post.
75+
> * Retrieving recent 'follow' actions for a user.
76+
> * Querying custom indexed data based on application-specific schemas.
77+
78+
#### Parameters
79+
| Name | Type | Required | Default | Description |
80+
|---------|----------------------------------------|----------|---------|-----------------------------------------------------|
81+
| options | [`IIndexOptions`](types#iindexoptions) | yes | - | Options that specify the criteria for index retrieval. |
82+
83+
#### Returns
84+
| Type | Description |
85+
|-------------------|---------------------------------------------------------------------------------------------------------------|
86+
| `Promise<object>` | A promise that resolves to an array of matched indexed values, ordered by block height. |
87+
5288
### `getVersion()`
5389

5490
> Gets the current version of the social contract.

0 commit comments

Comments
 (0)