Raw Queries & Subscriptions
While the @blocklet/server-js provides convenient helper methods for most common operations, you may sometimes need more flexibility. For these scenarios, you can execute raw GraphQL queries and subscriptions directly. This approach is useful when you need to access newly implemented API features not yet available through a dedicated SDK method or when constructing complex queries.
Raw Queries#
The doRawQuery method allows you to send any valid GraphQL query string directly to the Blocklet Server API endpoint.
doRawQuery(query)#
Sends a raw GraphQL query and returns the result as a Promise.
Parameters
Name | Type | Description |
|---|---|---|
|
| The GraphQL query string to execute. |
Returns
A Promise that resolves with the query result object.
Example
The following example demonstrates how to fetch basic information about the connected Blocklet Server.
const BlockletServerClient = require('@blocklet/server-js');
const client = new BlockletServerClient('http://localhost:4000/api');
async function getNodeInfo() {
try {
const query = `{
getNodeInfo {
code
info {
name
version
did
}
}
}`;
const result = await client.doRawQuery(query);
if (result.getNodeInfo.code === 'ok') {
console.log('Node Name:', result.getNodeInfo.info.name);
console.log('Node Version:', result.getNodeInfo.info.version);
console.log('Node DID:', result.getNodeInfo.info.did);
} else {
console.error('Failed to get node info.');
}
} catch (error) {
console.error('An error occurred:', error.message);
}
}
getNodeInfo();Example Response
{
"getNodeInfo": {
"code": "ok",
"info": {
"name": "My Blocklet Server",
"version": "1.8.6",
"did": "z1U9tV2z7Y5tX..."
}
}
}This method gives you full control over the data you request, allowing you to specify the exact fields you need, just as you would in a GraphQL client like GraphiQL.
Raw Subscriptions#
The doRawSubscription method allows you to listen for real-time events from Blocklet Server by sending a GraphQL subscription query.
doRawSubscription(query)#
Establishes a WebSocket connection and subscribes to a GraphQL event stream. While the method itself returns a Promise, you interact with the data stream using event listeners.
Parameters
Name | Type | Description |
|---|---|---|
|
| The GraphQL subscription string to execute. |
Returns
A Promise that resolves to a subscription object with an .on() method to listen for data and error events.
Example
While Blocklet Server currently does not expose any public GraphQL subscriptions, the client is equipped to handle them. If a subscription were available, you would use the following pattern to listen for events.
const BlockletServerClient = require('@blocklet/server-js');
const client = new BlockletServerClient('http://localhost:4000/api');
async function listenForUpdates() {
// Note: This is a hypothetical subscription for demonstration purposes.
const subscriptionQuery = `
subscription onBlockletStateChanged {
blockletStateChanged {
did
status
}
}
`;
try {
const subscription = await client.doRawSubscription(subscriptionQuery);
subscription.on('data', (data) => {
console.log('Received update:', data.blockletStateChanged);
});
subscription.on('error', (err) => {
console.error('Subscription error:', err);
});
console.log('Listening for blocklet state changes...');
} catch (error) {
console.error('Failed to start subscription:', error.message);
}
}
listenForUpdates();In this example, the code sets up a listener for incoming data. Each time the server pushes an update that matches the subscription query, the data event is fired with the new payload.
Using raw queries provides a powerful way to interact with the API when you need to go beyond the standard SDK methods. For troubleshooting your client-side implementation, see the next section on Debugging.