swiss-zx (Swiss Army Knife for zx)
A collection of helper functions and useful little things for Google's zx
Uses swiss-ak
Install
npm install swiss-zxor
yarn add swiss-zx$$ (double dollar)
cd
$$.cd(dir: string): ProcessPromiseChange the current working directory
await $$.pwd(); // '/Users/username'
await $$.cd('./some/folder');
await $$.pwd(); // '/Users/username/some/folder'| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | dir |
No | string |
'.' |
| Return Type |
|---|
ProcessPromise |
[↑ Back to $$ (double dollar) ↑]
pwd
$$.pwd(): Promise<string>Get the current working directory
await $$.pwd(); // '/Users/username'
await $$.cd('./some/folder');
await $$.pwd(); // '/Users/username/some/folder'| Return Type |
|---|
Promise<string> |
[↑ Back to $$ (double dollar) ↑]
ls
$$.ls(dir: string, flags: string[]): Promise<string[]>Wrapper for ls (list) command
await $$.ls('example') // ['a', 'b']| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | dir |
No | string |
'.' |
| 1 | flags |
No | string[] |
[] |
| Return Type |
|---|
Promise<string[]> |
[↑ Back to $$ (double dollar) ↑]
rm
$$.rm(item: string): ProcessPromiseWrapper for rm (remove) command
await $$.rm('example') // same as $`rm -rf 'example'`| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | item |
Yes | string |
| Return Type |
|---|
ProcessPromise |
[↑ Back to $$ (double dollar) ↑]
mkdir
$$.mkdir(item: string): ProcessPromiseWrapper for mkdir (make directory) command
await $$.mkdir('example') // same as $`mkdir -p 'example'`| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | item |
Yes | string |
| Return Type |
|---|
ProcessPromise |
[↑ Back to $$ (double dollar) ↑]
cp
$$.cp(a: string, b: string): ProcessPromiseWrapper for cp (copy) command
await $$.cp('example1', 'example2') // same as $`cp -r 'example1' 'example2'`| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | a |
Yes | string |
| 1 | b |
Yes | string |
| Return Type |
|---|
ProcessPromise |
[↑ Back to $$ (double dollar) ↑]
mv
$$.mv(a: string, b: string): ProcessPromiseWrapper for mv (move) command
await $$.mv('example1', 'example2') // same as $`mv 'example1' 'example2'`| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | a |
Yes | string |
| 1 | b |
Yes | string |
| Return Type |
|---|
ProcessPromise |
[↑ Back to $$ (double dollar) ↑]
touch
$$.touch(item: string): ProcessPromiseWrapper for touch (create blank file) command
await $$.touch('example') // same as $`touch 'example'`| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | item |
Yes | string |
| Return Type |
|---|
ProcessPromise |
[↑ Back to $$ (double dollar) ↑]
cat
$$.cat(item: string): ProcessPromiseWrapper for cat (concatenate) command
await $$.cat('example') // same as $`cat 'example'`| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | item |
Yes | string |
| Return Type |
|---|
ProcessPromise |
[↑ Back to $$ (double dollar) ↑]
grep
$$.grep(pattern: string, file: string): Promise<string[]>Wrapper for grep (Global Regular Expression Print) command
await $$.grep('example', '.') // same as $`grep 'example' '.'`| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | pattern |
Yes | string |
| 1 | file |
Yes | string |
| Return Type |
|---|
Promise<string[]> |
[↑ Back to $$ (double dollar) ↑]
find
$$.find(dir: string, options: FindOptions): Promise<string[]>Helper function for finding files
await $$.find('.', { type: 'f' }) // ['a', 'b']| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | dir |
No | string |
'.' |
| 1 | options |
No | FindOptions |
{} |
| Return Type |
|---|
Promise<string[]> |
[↑ Back to $$ (double dollar) ↑]
FindOptions
$$.FindOptions;Options for $$.find (and related other tools)
| Property | Required | Type | Description |
|---|---|---|---|
type |
No | FindType | Type of item to find |
mindepth |
No | number | Minimum depth to search |
maxdepth |
No | number | Maximum depth to search |
name |
No | string | Name of file/directory to find |
ext |
No | string | Shortcut for regex-ing the file extension |
regex |
No | string | Regular expression to match |
removePath |
No | boolean | Removes the path from the result |
contentsOnly |
No | boolean | Ensures input path has a trailing slash |
removeTrailingSlashes |
No | boolean | Removes trailing slashes from the results |
showHidden |
No | boolean | Includes files that start with a dot |
[↑ Back to $$ (double dollar) ↑]
FindType
$$.FindType;Type of item to find
| Description | |
|---|---|
| d | directory |
| f | regular file |
| b | block special |
| c | character special |
| l | symbolic link |
| p | FIFO |
| s | socket |
[↑ Back to $$ (double dollar) ↑]
findDirs
$$.findDirs(dir: string, options: FindOptions): Promise<string[]>Find all directories in a given directory (shallow)
await $$.findDirs('.') // ['a', 'b']| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | dir |
No | string |
'.' |
| 1 | options |
No | FindOptions |
{} |
| Return Type |
|---|
Promise<string[]> |
[↑ Back to $$ (double dollar) ↑]
findFiles
$$.findFiles(dir: string, options: FindOptions): Promise<string[]>Find all files in a given directory (shallow)
await $$.findFiles('.') // ['a', 'b']| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | dir |
No | string |
'.' |
| 1 | options |
No | FindOptions |
{} |
| Return Type |
|---|
Promise<string[]> |
[↑ Back to $$ (double dollar) ↑]
findModified
$$.findModified(dir: string, options: FindOptions): Promise<ModifiedFile[]>Similar to $$.find, but returns a list of ModifiedFile objects, which includes information on what each item was last modified.
await $$.findModified('.')
// [
// {
// lastModified: 1689206400000,
// path: './a.mp4',
// dir: '.',
// folders: ['.'],
// name: 'a',
// ext: 'mp4',
// filename: 'a.mp4'
// }
// ]| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | dir |
No | string |
'.' |
| 1 | options |
No | FindOptions |
{} |
| Return Type |
|---|
Promise<ModifiedFile[]> |
[↑ Back to $$ (double dollar) ↑]
ModifiedFile
$$.ModifiedFile;Returned by $$.findModified.
Extends swiss-node's ExplodedPath, adding a new lastModified number property.
{
lastModified: 1689206400000,
path: './a.mp4',
dir: '.',
folders: ['.'],
name: 'a',
ext: 'mp4',
filename: 'a.mp4'
}[↑ Back to $$ (double dollar) ↑]
lastModified
$$.lastModified(path: string): Promise<number>Returns the last modified time of a file or files within a directory.
await $$.lastModified('a.mp4') // 1689206400000| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | path |
Yes | string |
| Return Type |
|---|
Promise<number> |
[↑ Back to $$ (double dollar) ↑]
rsync
$$.rsync(a: string, b: string, flags: string[], progressBarOpts: Partial<progressBar.ProgressBarOptions>): Promise<any>Wrapper for rsync command
await $$.rsync('example1', 'example2') // same as $`rsync -rut 'example1' 'example2'`| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | a |
Yes | string |
|
| 1 | b |
Yes | string |
|
| 2 | flags |
No | string[] |
[] |
| 3 | progressBarOpts |
No | Partial<progressBar.ProgressBarOptions> |
| Return Type |
|---|
Promise<any> |
[↑ Back to $$ (double dollar) ↑]
sync
$$.sync(a: string, b: string, progressBarOpts: Partial<progressBar.ProgressBarOptions>): Promise<any>Helper function for syncing files
await $$.sync('example1', 'example2') // same as $`rsync -rut 'example1' 'example2' --delete`| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | a |
Yes | string |
| 1 | b |
Yes | string |
| 2 | progressBarOpts |
No | Partial<progressBar.ProgressBarOptions> |
| Return Type |
|---|
Promise<any> |
[↑ Back to $$ (double dollar) ↑]
isFileExist
$$.isFileExist(file: string): Promise<boolean>Check if a file exists
await $$.isFileExist('example') // true| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | file |
Yes | string |
| Return Type |
|---|
Promise<boolean> |
[↑ Back to $$ (double dollar) ↑]
isDirExist
$$.isDirExist(dir: string): Promise<boolean>Check if a directory exists
await $$.isDirExist('example') // true| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | dir |
Yes | string |
| Return Type |
|---|
Promise<boolean> |
[↑ Back to $$ (double dollar) ↑]
readFile
$$.readFile(filepath: string): Promise<string>Read a file's contents
await $$.readFile('example') // 'hello world'| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | filepath |
Yes | string |
| Return Type |
|---|
Promise<string> |
[↑ Back to $$ (double dollar) ↑]
writeFile
$$.writeFile(filepath: string, contents: string): Promise<void>Write to a file
await $$.writeFile('example', 'hello world') // saves a new file called 'example' with the contents 'hello world'| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | filepath |
Yes | string |
| 1 | contents |
Yes | string |
| Return Type |
|---|
Promise<void> |
[↑ Back to $$ (double dollar) ↑]
readJSON
$$.readJSON<T>(filepath: string): Promise<T>Read a JSON file
await $$.readJSON('example.json') // { hello: 'world' }| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | filepath |
Yes | string |
| Return Type |
|---|
Promise<T> |
[↑ Back to $$ (double dollar) ↑]
writeJSON
$$.writeJSON<T>(obj: T): Promise<T>Write to a JSON file
await $$.writeJSON('example.json', { hello: 'world' }) // saves a new file called 'example.json' with the contents {'hello':'world'}| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | obj |
Yes | T |
| Return Type |
|---|
Promise<T> |
[↑ Back to $$ (double dollar) ↑]
pipe
$$.pipe(processes: ((index?: number, arg?: T) => ProcessPromise)[], arg: T): ProcessPromisePipes a series of $ or $$ commands sequentially
await $$.pipe([
() => gm.convert(basePath, gm.PIPE, opts1),
() => gm.composite(changePath, gm.PIPE, gm.PIPE, changePath, opts2)
]);| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | processes |
Yes | ((index?: number, arg?: T) => ProcessPromise)[] |
| 1 | arg |
No | T |
| Return Type |
|---|
ProcessPromise |
[↑ Back to $$ (double dollar) ↑]
exiftool
$$.exiftool(file: string, setAttr: ExifToolAttributesObj, getAttr: (ExifToolAttributes | string)[], outFile: string): Promise<ExifToolAttributesObj>Usage:
$$.exiftool('/path/to/file.jpg', {'Copyright': 'Eg val'});
$$.exiftool('/path/to/file.jpg', {'Copyright': 'Eg val'}, undefined, '/path/to/new_file.jpg');| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | file |
Yes | string |
| 1 | setAttr |
No | ExifToolAttributesObj |
| 2 | getAttr |
No | (ExifToolAttributes | string)[] |
| 3 | outFile |
No | string |
| Return Type |
|---|
Promise<ExifToolAttributesObj> |
[↑ Back to $$ (double dollar) ↑]
ExifToolAttributesObj
$$.ExifToolAttributesObj;Interface for the attributes returned by exiftool
[↑ Back to $$ (double dollar) ↑]
ExifToolAttributes
$$.ExifToolAttributes;Type for the names of the attributes returned by exiftool
[↑ Back to $$ (double dollar) ↑]
utils
intoLines
$$.utils.intoLines(out: ProcessOutput): string[]Turns ProcessOutput into string array, split into lines
utils.intoLines($`echo "1\n2\n3"`) // ['1', '2', '3']| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | out |
Yes | ProcessOutput |
| Return Type |
|---|
string[] |
[↑ Back to $$ (double dollar) ↑]
os
closeFinder
closeFinder(): Promise<void>
os.closeFinder(): Promise<void>Close all Mac OS X Finder windows.
await closeFinder();| Return Type |
|---|
Promise<void> |
ffmpegTools
ffmpeg
ffmpeg(command: () => ProcessPromise, progressFileName: string, totalFrames: number, progressBarOpts: progressBar.ProgressBarOptions): Promise<void>
ffmpegTools.ffmpeg(command: () => ProcessPromise, progressFileName: string, totalFrames: number, progressBarOpts: progressBar.ProgressBarOptions): Promise<void>Wrapper for ffmpeg command that provides progress bar to track progress
const progBarOpts = {}; // Same options as getProgressBar
await ffmpeg(() => $`ffmpeg -y -i ${a} ${b} -progress ${pr}`, pr, framesNum, progBarOpts);| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | command |
No | () => ProcessPromise |
() => $`ffmpeg -progress pr.txt` |
| 1 | progressFileName |
No | string |
'pr.txt' |
| 2 | totalFrames |
No | number |
1 |
| 3 | progressBarOpts |
No | progressBar.ProgressBarOptions |
{} |
| Return Type |
|---|
Promise<void> |
toFFmpegTimeFormat
ffmpegTools.toFFmpegTimeFormat(time: ms): stringConvert a number of milliseconds to a time format usable by FFmpeg.
ffmpegTools.toFFmpegTimeFormat(minutes(3)); // '03:00.000'
ffmpegTools.toFFmpegTimeFormat(minutes(3) + seconds(21)); // '03:21.000'
ffmpegTools.toFFmpegTimeFormat(minutes(3) + seconds(21) + 456); // '03:21.456'| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | time |
Yes | ms |
| Return Type |
|---|
string |
getProbe
ffmpegTools.getProbe(file: string): Promise<ProbeResult>Get the probe of a file as an object
const probe = await getProbe('file.mp4'); // { width: 1280, height: 720, ... }| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | file |
Yes | string |
| Return Type |
|---|
Promise<ProbeResult> |
ProbeResult
ffmpegTools.ProbeResult;Note: this interface is a guide, and other properties may exist, and some may be have different types
getProbeValue
ffmpegTools.getProbeValue(file: string, propertyName: string): Promise<string>Get a value from ffprobe output
const probe = await getProbe('file.mp4', 'width'); // '1280'| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | file |
Yes | string |
| 1 | propertyName |
Yes | string |
| Return Type |
|---|
Promise<string> |
getTotalFrames
ffmpegTools.getTotalFrames(list: string | string[]): Promise<number>Get the total number of frames in a video file.
const num = await getTotalFrames('video.mp4'); // 120 (2 secs at 60fps)| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | list |
No | string | string[] |
| Return Type |
|---|
Promise<number> |
gm
convert
gm.convert(inPath: string, outPath: string, flags: ConvertFlagsObj): ProcessPromiseWrapper function for gm (GraphicsMagick) convert command
const converted = await gm.convert(input, output, {});| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | inPath |
No | string |
PIPE |
| 1 | outPath |
No | string |
PIPE |
| 2 | flags |
No | ConvertFlagsObj |
{} |
| Return Type |
|---|
ProcessPromise |
ConvertFlagsObj
gm.ConvertFlagsObj;Options configuration for the gm.convert function
Extends CommonFlagsObj
composite
gm.composite(changePath: string, basePath: string, outPath: string, maskPath: string, flags: ChangeAndMaskFlags | CompositeFlagsObj): ProcessPromiseWrapper function for gm (GraphicsMagick) composite command
Has extra functionality for using a 'Screen' blending mode (similar to Photoshop)
const composited = await gm.composite(change, base, out, undefined, {});| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | changePath |
No | string |
PIPE |
| 1 | basePath |
No | string |
PIPE |
| 2 | outPath |
No | string |
PIPE |
| 3 | maskPath |
No | string |
'' |
| 4 | flags |
No | ChangeAndMaskFlags | CompositeFlagsObj |
{} |
| Return Type |
|---|
ProcessPromise |
CompositeFlagsObj
gm.CompositeFlagsObj;Options configuration for the gm.composite function
Extends CommonFlagsObj
ChangeAndMaskFlags
gm.ChangeAndMaskFlags;If compositing with a mask, you can specify the change and mask flags separately
{
change?: CompositeFlagsObj;
mask?: CompositeFlagsObj;
}pipe
gm.pipe(inPath: string, outPath: string, processes: ((pipeIn?: string, pipeOut?: string, index?: number) => ProcessPromise)[]): ProcessPromisePipe a series of gm commands together
WARNING: If inPath is provided, it will be piped in to first process WARNING: If outPath is provided, it will be piped out from last process
await pipe(basePath, outPath, [
(p) => convert(p, p, opts1),
(p) => composite(changePath, p, p, changePath, opts2)
]);
await pipe(undefined, undefined, [
(p) => convert(basePath, p, opts1),
(p) => composite(changePath, p, outPath, changePath, opts2)
]);| # | Parameter Name | Required | Type | Default |
|---|---|---|---|---|
| 0 | inPath |
No | string |
|
| 1 | outPath |
No | string |
|
| 2 | processes |
No | ((pipeIn?: string, pipeOut?: string, index?: number) => ProcessPromise)[] |
[] |
| Return Type |
|---|
ProcessPromise |
PIPE
gm.PIPE;A shortcut constant for the GraphicsMagick pipe path which is MIFF:-
This can be used in place any path parameter to pipe the result of a gm command to another gm command
Types
CommonFlagsObj
gm.CommonFlagsObj;Option configuration options that are common to both gm.convert and gm.composite
FlagsObj
gm.FlagsObj;ConvertFlagsObj & CompositeFlagsObj
channel
gm.channel;'red' | 'green' | 'blue' | 'cyan' | 'magenta' | 'yellow' | 'black' | 'opacity' | 'gray' | 'matte'
utils
flagsObjToArray
gm.utils.flagsObjToArray(obj: gm.FlagsObj): (string | number)[]Converts a FlagsObj to an array of flags and values (for zx).
gm.utils.flagsObjToArray({ channel: 'red' }); // [ '-channel', 'red' ]
gm.utils.flagsObjToArray({ displace: '10' }); // [ '-displace', '10' ]
gm.utils.flagsObjToArray({ resize: '1080', fill: 'gray', gravity: 'SouthEast' });
// ['-resize', '1080', '-fill', 'gray', '-gravity', 'SouthEast']
gm.utils.flagsObjToArray({ brightness: 150, saturation: 50, hue: 200 });
// [ '-modulate', '150,50,200' ]| # | Parameter Name | Required | Type |
|---|---|---|---|
| 0 | obj |
Yes | gm.FlagsObj |
| Return Type |
|---|
(string | number)[] |
channelComposeCopyMap
gm.utils.channelComposeCopyMap;A dictionary for mapping channel names to their respective compose copy names.
gm.utils.channelComposeCopyMap['red'] // 'CopyRed'
gm.utils.channelComposeCopyMap['magena'] // 'CopyMagenta'
gm.utils.channelComposeCopyMap['gray'] // 'Copy'supportedFlags
gm.utils.supportedFlags;An object containing the supported flags and their types (or options).
GMCommand
gm.utils.GMCommand;An internal string indictor for which gm command to use.
Only used in configuration for gm.utils.SupportedFlag.
'convert' | 'composite'SupportedFlag
gm.utils.SupportedFlag;An internal configuration object for a supported flag.