SDTFClient

The client to use SDTFEngine and Parsers Pipeline APIs. It provides methods for interacting with the token tree of a repository.

Properties

engine

This property represents the SDTF engine used by the SDTFClient.

readonly engine: SDTFEngine;

repository

This property represents the repository that the SDTFClient is interacting with.

readonly repository: {
    readonly id: string;
    readonly name: string;
    readonly version: number;
    readonly createdAt: string;
    readonly updatedAt: string;
};

Methods

getJSONTokenTree

Returns the JSON token tree from the current repository.

getJSONTokenTree(): SpecifyDesignTokenFormat;

clone

Create a new SDTFClient instance to avoid mutating the current token tree. Especially useful when you want to perform multiple distinct operations on the same token tree.

clone(): SDTFClient;

pick

Narrow the current token tree by picking a subtree based on the given path.

pick(path: Array<string>): this;

query

Create a clone of the current SDTF and only keep the selection of the query. When creating a new tree it's possible that tokens, groups and collections names will collide.

query(query: SDTFQuery, dedupeFn?: MergeDedupeFn): SDTFClient;

renameNode

Rename a node to a new name. If you specify a type, it'll rename the node only if it's matching the type parameter. If it doesn't, it'll throw an error.

renameNode(options: {
    atPath: Array<string>;
    name: string;
    type?: 'group' | 'collection' | 'token';
}): this;

Example

sdtf.renameNode({ atPath: ['my', 'group'], name: 'newName' })

update

Execute an update on the current token tree. Note that the update won't be applied to the remote repository.

update(...updaters: Array<Updater>): this;

withQuery

Execute multiple updater functions with the same query.

withQuery(query: SDTFQuery): {
    update: (...updaters: Array<Updater>) => SDTFClient;
};

resolveAliases

Resolve aliases in the current token tree. Useful before pick to avoid unresolvable aliases.

resolveAliases(): this;

remove

Narrow the current token tree by removing any matching node based on the given query.

remove(query: SDTFQuery): this;

reset

Resets the current token tree to its initial value. The initial value being the token tree of the repository at the time of the creation of the first SDTFClient instance.

reset(): this;

executeEngine

Tap into the current token tree to perform custom side effects.

executeEngine(fn: (engine: SDTFEngine) => void): this;

forEachTokenState

Iterate against the tokenStates of the current token tree.

forEachTokenState(fn: (tokenState: TokenState, engine: SDTFEngine) => void): this;

mapTokenStates

Iterate against the tokenStates of the current token tree, and accumulate the results in an array.

mapTokenStates<T>(fn: (tokenState: TokenState, engine: SDTFEngine) => T): Array<T>;

getTokenState

Get a token state for a given path.

getTokenState(path: Array<string>): TokenState | undefined;

getAllTokenStates

Get all the token states.

getAllTokenStates(): Array<TokenState>;

forEachCollectionState

Iterate against the collectionStates of the current token tree.

forEachCollectionState(fn: (collectionState: CollectionState, engine: SDTFEngine) => void): this;

mapCollectionStates

Iterate against the collectionStates of the current token tree, and accumulate the results in an array.

mapCollectionStates<T>(fn: (collectionState: CollectionState, engine: SDTFEngine) => T): Array<T>;

getCollectionState

Get a collection state for a given path.

getCollectionState(path: Array<string>): CollectionState | undefined;

getAllCollectionStates

Get all the collection states.

getAllCollectionStates(): Array<CollectionState>;

forEachGroupState

Iterate against the groupStates of the current token tree.

forEachGroupState(fn: (groupState: GroupState, engine: SDTFEngine) => void): this;

mapGroupStates

Iterate against the groupStates of the current token tree, and accumulate the results in an array.

mapGroupStates<T>(fn: (groupState: GroupState, engine: SDTFEngine) => T): Array<T>;

getGroupState

Get a group state for a given path.

getGroupState(path: Array<string>): GroupState | undefined;

getAllGroupStates

Get all the group states.

getAllGroupStates(): Array<GroupState>;

forEachQueryResult

Iterate against the nodeStates given by the query.

forEachQueryResult(query: SDTFQuery, fn: (treeNodeState: SDTFNodeState, engine: SDTFEngine, queryResult: QueryResult) => void): this;

mapQueryResults

Iterate against the nodeStates given by the query, and accumulate the result in an array.

mapQueryResults<T>(query: SDTFQuery, fn: (treeNodeState: SDTFNodeState, engine: SDTFEngine, queryResult: QueryResult) => T): T[];

createParsersPipelines

Create a parsers engine executor from the custom or built-in parser functions passed as arguments. All pipelines are executed in parallel, if you need to chain parsers, have a look to the chainParserFunctions util.

createParsersPipelines(
  ...parsers: Array<ParserFunction<SDTFEngineDataBox>>
): () => Promise<ParsersEngineResults>;

createParsersPipelinesFromRules

Create a parsers engine executor from the built-in parser rules passed as arguments. All pipelines are executed in parallel, if you need to chain parsers, have a look to the chainParserFunctions util.

createParsersPipelinesFromRules(
  ...parsers: Array<BuiltInGenerationParserRule>
): () => Promise<ParsersEngineResults>;