Connection
The protocol between a client and its engine: requests, replies, and what the engine sends back after a command
(EmissionConfig). For apps that talk to the engine directly.
Types
EmissionConfig
type EmissionConfig = {
safeApi?: boolean;
sendGraphic_AdvancedNotifications: boolean;
sendGraphic_Compressed: boolean;
sendGraphic_Immediately: boolean;
sendGraphic_ImmediatelyBinary: boolean;
sendGraphic_Invisible: boolean;
sendGraphic_Kernel: boolean;
sendGraphic_Multipackage: boolean;
sendGraphic_Sketch: boolean;
sendGraphic_StructureObj: boolean;
sendGraphic_UseDraco: boolean;
sendGraphic_UseDracoHybrid: boolean;
sendMessages: boolean;
sendMessages_Immediately: boolean;
sendMessages_MinLevel: number;
sendStructure: boolean;
sendStructure_Compressed: boolean;
sendStructure_Immediately: boolean;
sendStructure_ImmediatelyBinary: boolean;
sendStructure_Patch: boolean;
storeState: boolean;
};
The engine's per-connection emission flags: what it sends back after a command, and in which form.
Content flags decide WHAT comes back after a command (structure tree, the four graphic categories, messages); delivery flags decide HOW (patches vs snapshot, streamed immediately vs bundled on the Result, binary/compressed, multipackage). Two commands ignore the content flags on purpose: GetTree/Sync always deliver the structure, v1.common.requestVisualisation always delivers its graphic - they are explicit requests.
Read and change them with getEmissionConfig/setEmissionConfig of a client, or for a stretch of commands
with BuerliCadFacade.utils.withEmissionConfig. Not to be confused with v1.common.setDatabaseSettings, which
decides what the engine tessellates.
Example
import { BuerliCadFacade } from '@buerli.io/classcad'
import type { EmissionConfig } from '@buerli.io/classcad'
// A study of twenty variants: no graphic after each change, only the volume
const noGraphic: Partial<EmissionConfig> = { sendGraphic_Kernel: false, sendGraphic_Sketch: false }
const volumes = await BuerliCadFacade.utils.withEmissionConfig(facade.drawingId, noGraphic, async () => {
const result: number[] = []
for (let length = 50; length < 250; length += 10) {
await facade.api.v1.part.updateExpression({ id: part, toUpdate: [{ name: 'length', value: length }] })
const mass = await facade.api.v1.part.calculateMassProperties({ id: part })
if (mass) result.push(mass.volume)
}
return result
})
// The flags are back: the tree, and with it the graphic, once
await BuerliCadFacade.utils.fetchTree(facade.drawingId)
Properties
IComClient
What a client does for buerli: connect a drawing to an engine, run commands on it and load its structure.
AwvNodeClient implements it; the clients (WASMClient, WSClient, SocketIOClient) extend that.
Methods
connect()
connect(): Promise<IComClient>;
Connects to the engine; resolves once the drawing's structure tree is loaded and API calls can be made.
Returns
Promise<IComClient>
disconnect()
disconnect(): Promise<IComClient>;
Closes the connection to the engine.
Returns
Promise<IComClient>
executeMiddleware()
executeMiddleware(command, data): {
};
Sends a command of the server's own (a middleware command) with data.
Parameters
| Parameter | Type | Description |
|---|---|---|
command | string | The command's name. |
data | any | Fields sent with the command. |
Returns
{
}
executeRequest()
executeRequest(
task,
streamMap?,
options?
): {
};
Runs task (API calls) on the engine. Rejects with the reply when it carries an error.
Parameters
| Parameter | Type | Description |
|---|---|---|
task | Task | The API calls to run, e.g. [{ 'v1.part.create': [{ name: 'Part' }] }]. |
streamMap? | StreamMap | Data the calls read, by stream key (a file to import, for example). |
options? | RequestOptions | Options of the request, such as undoable. |
Returns
{
}
getEmissionConfig()
getEmissionConfig(): Promise<EmissionConfig>;
Per-connection emission config (what the engine pushes back: structure,
graphic categories, messages, delivery form). getEmissionConfig returns the
effective flags, setEmissionConfig merges a partial set and returns the result.
Rejects with an Error named EMISSION_CONFIG_UNSUPPORTED on engines that
predate the GetEmissionConfig/SetEmissionConfig commands (old WASM builds, old servers).
Returns
Promise<EmissionConfig>
redo()
redo(options?): {
};
Steps forward in the drawing's undo history.
Parameters
| Parameter | Type |
|---|---|
options? | RedoOptions |
Returns
{
}
requestTree()
requestTree(): {
};
Loads the drawing's structure tree from the engine into the buerli store.
Returns
{
}
setEmissionConfig()
setEmissionConfig(partial): Promise<EmissionConfig>;
Merges partial into the connection's emission config and resolves to the effective flags. Rejects with an
Error named EMISSION_CONFIG_UNSUPPORTED on engines that predate the command.
Parameters
| Parameter | Type | Description |
|---|---|---|
partial | Partial<EmissionConfig> | The flags to change; the others stay as they are. |
Returns
Promise<EmissionConfig>
undo()
undo(options?): {
};
Steps back in the drawing's undo history.
Parameters
| Parameter | Type |
|---|---|
options? | UndoOptions |
Returns
{
}
RedoOptions
type RedoOptions = {
[key: string]: any;
state?: string;
};
Options of a redo; keys other than state travel with it to the engine.
Indexable
[key: string]: any
Properties
| Property | Type | Description |
|---|---|---|
state? | string | The state of the undo history to go forward to, a name from the drawing's cad.states.stack. |
RequestOptions
type RequestOptions = {
[key: string]: any;
undoable?: boolean;
};
Options of a request; keys other than undoable travel with it to the engine.
Indexable
[key: string]: any
Properties
| Property | Type | Description |
|---|---|---|
undoable? | boolean | Makes the request a step of the drawing's undo history, named after its first API call. |
ServerError
type ServerError = {
errorCode: number;
errorMessage: string;
errorState: number;
};
An error in the form older engines report it, before messages; clients turn it into a ServerMessage.
Properties
ServerMessage
type ServerMessage = Message;
A message of the engine about a command: its text, code and level (a MessageLevel).
ServerRequest
type ServerRequest = {
command: | "Execute"
| "GetTree"
| "GetEmissionConfig"
| "SetEmissionConfig"
| string;
config?: Partial<EmissionConfig>;
options?: RequestOptions;
streamData?: StreamMap;
task?: Task;
};
A request to the engine: a command, and what it needs.
Properties
| Property | Type | Description |
|---|---|---|
command | | "Execute" | "GetTree" | "GetEmissionConfig" | "SetEmissionConfig" | string | The command: Execute runs task, GetTree returns the structure tree; the engine knows more. |
config? | Partial<EmissionConfig> | Only for the SetEmissionConfig command: the partial EmissionConfig to merge. The engine ignores this field on every other command - emission flags are a per-CONNECTION setting (see IComClient.setEmissionConfig), not per request. |
options? | RequestOptions | Options of the request. |
streamData? | StreamMap | For Execute: the data the calls read, by stream key. |
task? | Task | For Execute: the API calls to run. |
ServerResponse
type ServerResponse = {
maxLevel?: number;
messages?: Message[];
result?: any;
streamData?: {
[key: string]: string;
};
};
The engine's reply to a request: the result, and the messages that came with it.
A client rejects with the reply when maxLevel is an error or worse.
Properties
StreamData
type StreamData = any;
The data of one stream: the content of a file, for example.
StreamMap
type StreamMap = Record<string, StreamData>;
Data sent with a request or returned by it, by stream key; API calls refer to it by that key.
Task
type Task =
| {
[apiCommand: string]: (string | number)[];
}[]
| string;
What an Execute request runs: a list of API calls, or a command as a string.
Each API call is { '<version>.<namespace>.<function>': [args] }.
UndoOptions
type UndoOptions = {
[key: string]: any;
state?: string;
};
Options of an undo; keys other than state travel with it to the engine.
Indexable
[key: string]: any
Properties
| Property | Type | Description |
|---|---|---|
state? | string | The state of the undo history to go back to, a name from the drawing's cad.states.stack. |
Constants
EMISSION_CONFIG_UNSUPPORTED
const EMISSION_CONFIG_UNSUPPORTED: "EmissionConfigUnsupported" = 'EmissionConfigUnsupported';
Error.name of the rejection when the engine does not support GetEmissionConfig/SetEmissionConfig.