Specify SDK Cheatsheet

On this page you'll find a lot of common actions you'll probably want to perform when using the SDK

Creating Specify and SDTF clients

You will first create a Specify client, then authenticate, then create a SDTF client by fetching the repository token tree.

import { createSpecifyClient } from "@specifyapp/sdk";

const specifyClient = createSpecifyClient();
await specifyClient.authenticate("<YOUR_PERSONAL_ACCESS_TOKEN_VAR>");

const sdtfClient = 
  await specifyClient.getSDTFClientByRepositoryName("<YOUR_SPECIFY_REPO_NAME>");
  
  console.log('Repository name',sdtfClient.repository.name)

Updating tokens

The following example is only an overview, if you need more details you can have a look here.

import { updaters } from '@specifyapp/sdk'

sdtfClient.update(
  updaters.color({ toFormat: 'hex' }, { where: { token: '^color-' }}),
);

Convert a token to XXX

The following example is only an overview, if you need more details you can have a look here.

import {
  dimensionToCss,
  breakpointToCss,
  colorToCss,
  createResolveAliasStrategy 
} from '@specify/sdk/css'

const strategy = createResolveAliasStrategy();

const outputs = sdtfClient.mapTokenStates(tokenState => 
  tokenState.matchByType(
    {
      dimension: dimensionToCss(strategy) // Output example: '12px'
      breakpoint: breakpointToCss(strategy) // Output example: '12px'
      color: colorToCss(strategy) // Output example: '#ff00ff'
    }, 
    _ => undefined
  )
);

Execute a parser

The following example is only an overview, if you need more details you can have a look here.

import { parsers } from '@specify/sdk'

const executePipelines = sdtfClient
  .createParsersPipelines(
    parsers.toCssCustomProperties({ filePath: 'myFile.css' }),
  );
const parsersEngineResults = await executePipelines();

Retrieving data

Get a specific token

const tokenState = sdtfClient.getTokenState(['path', 'to', 'token']);

Get all the tokens

const tokenStates = sdtfClient.getAllTokenStates();

Map over all the tokens

const results = sdtfClient.mapTokenStates(tokenState => ...);

Get a specific group

const group = sdtfClient.getGroupState(['path', 'to', 'myGroup']);

Get all the groups

const groups = sdtfClient.getAllGroupStates();

Map over all the groups

const results = sdtfClient.mapGroupStates(tokenState => ...);

Get a specific collection

const collection = sdtfClient.getCollectionState(['path', 'to', 'myCollection']);

Get all collections

const collections = sdtfClient.getAllCollectionStates();

Map over all the collections

const results = sdtfClient.mapCollectionStates(tokenState => ...);

Filtering data

Keeping a sub-graph from a path

If you only want a specific portion of the graph, you can cherry-pick using the pick function:

const colors = sdtfClient.pick(['colors']);

Keeping the children of a path

If you only want the children of a specific portion of the graph you can use the pick function this way:

const colors = sdtfClient.pick(['colors', '*']);

Query a specific set of data

You can use the query method of the SDTFClient to create a copy of the current SDTF with only the tokens that'll match your query:

const colorAndTextStyleOnlySdtf = sdtfClient.query({
  where: {
    token: '.*',
    withTypes: {
      include: ['color', 'textStyle']
    }
  }
});

You can find all the details about querying the data here.

Remove tokens from the SDTF

You can use the remove method to delete tokens based on a query:

sdtfClient
  .remove({ where: { token: '^Blue$', select: true } })

Renaming tokens

Rename a node

By not specifying any type, the method will rename any node as long as the path is valid.

sdtfClient.renameNode({ atPath: ['my', 'path' ], name: 'newName' });

Rename a collection

By specifying the type, the method will rename only a collection node.

sdtfClient.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'collection'
});

Rename a group

By specifying the type, the method will rename only a group node.

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

Rename a token

By specifying the type, the method will rename only a token node.

sdtf.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'token'
});