@segment/prism v0.1.9
prism
A templating engine for generating strongly typed analytics clients across languages using the schema defined by a Tracking Plan
Install
Yarn
yarn global add @segment/prism
npm
npm install @segment/prism -g
Run
The following will generate a client api based on the Tracking Plan with id rs_15cyAM8Ce7hudhJ2dH50xIkywoe
at the the path defined by outputPath
prism gen-js \
--id rs_15cyAM8Ce7hudhJ2dH50xIkywoe \
--token [your_token] \
--outputPath .
An API token can be obtained by navigating to the API Keys
page for a workspace containing the Tracking Plan you intend to generate a client for:
https://app.segment.com/{your_workspace_name}/settings/api-keys
To run this tool against a local Tracking Plan file, run the following command (see the file referenced by the --inputPath
switch as an example of the format that's expected):
prism gen-ts \
--inputPath src/lib/__tests__/trackingPlanFixture.json \
--outputPath .
To get a description of each of the provided arguments for this command, run prism gen-ts --help
Options:
--help Show help [boolean]
--version Show version number [boolean]
--id The resource id for a Tracking Plan [string]
--token The auth token for a user [string]
--outputPath The output path for the files [string]
--inputPath The path to a local tracking plan file [string]
To get a list of available language targets, run prism --help
Commands:
gen-android Generate a strongly typed Android client from a Tracking Plan
gen-js Generate an analytics.js wrapper from a Tracking Plan
gen-ts Generate a typescript type definitions from a Tracking Plan
Options:
--help Show help [boolean]
--version Show version number [boolean]
Build and run locally WIP
From within this project directory:
npm install
npm run build
# The build library is now available in ./dist
node ./dist/index.js gen-js \
--id rs_15cyAM8Ce7hudhJ2dH50xIkywoe \
--token [your_token] \
--outputPath .
Add New Language Targets
(TODO - extend this section)
1) Create a gen-{your-lang-here}.ts
file in src/commands
(see existing commands for examples to work from)
2) Export the variables command
(the name of the command), desc
(its description), builder
(an object that captures the parameters your command takes -- in the majority of cases you can just re-export builder
in src/lib/index.ts
) and handler
-- covered below
3) The handler
export is the function that accepts an array of Tracking Plan events and a reference to an api
instance -- (note the handler must be wrapped by the getTypeTrackHandler()
function) here you can extract type information and other metadata from the events and use it to format a data payload that can be provided to the api
instance's render()
method
/*
* gen-go.ts
*/
export const handler = getTypedTrackHandler((events, api) => {
const structs = transformEventsIntoGoStructs(events)
return api.render('analytics', 'go', {
structs
})
}, command)
The first argument of render specifies the name of a template file (in the case of this hypothetical go client generator, this would be a reference to a handlebars template file at src/resources/go/analytics.hbs
) -- this works similar in spirit to an express view engine. The name of the language in gen-{language}
will correspond to the resource path where templates are found
The second argument to render specifies the generated file's extension (analytics.go
)
A single promise must be returned from a handler -- in order to render multiple files, use a Promise.all()
to concurrently render them to disk:
/*
* gen-node.ts
*/
export const handler = getTypedTrackHandler((events, api) => {
// ...
return Promise.all([
api.render('package', 'json', {
versionInfo,
otherData
}),
api.render('Readme', 'md', {
models,
someOtherStuff
}),
api.render('index', 'js', {
models
})
])
}, command)
4) To give an idea of what a generator produces, include the ouput of your command in samples/{language}
(TODO: standarize a source input to use for generating samples when the --file
option lands for specifying a local json file)