A collection of helper functions and useful little things for Google's zx
Uses swiss-ak
npm install swiss-zx
or
yarn add swiss-zx
$$.cd(dir: string): ProcessPromise
Change 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(): 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(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(item: string): ProcessPromise
Wrapper 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(item: string): ProcessPromise
Wrapper 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(a: string, b: string): ProcessPromise
Wrapper 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(a: string, b: string): ProcessPromise
Wrapper 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(item: string): ProcessPromise
Wrapper 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(item: string): ProcessPromise
Wrapper 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(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(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;
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;
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(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(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(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;
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(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(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(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(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(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(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(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<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<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(processes: ((index?: number, arg?: T) => ProcessPromise)[], arg: T): ProcessPromise
Pipes 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(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;
Interface for the attributes returned by exiftool
[↑ Back to $$ (double dollar) ↑]
$$.ExifToolAttributes;
Type for the names of the attributes returned by exiftool
[↑ Back to $$ (double dollar) ↑]
$$.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) ↑]
closeFinder(): Promise<void>
os.closeFinder(): Promise<void>
Close all Mac OS X Finder windows.
await closeFinder();
Return Type |
---|
Promise<void> |
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> |
ffmpegTools.toFFmpegTimeFormat(time: ms): string
Convert 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 |
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> |
ffmpegTools.ProbeResult;
Note: this interface is a guide, and other properties may exist, and some may be have different types
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> |
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(inPath: string, outPath: string, flags: ConvertFlagsObj): ProcessPromise
Wrapper 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 |
gm.ConvertFlagsObj;
Options configuration for the gm.convert
function
Extends CommonFlagsObj
gm.composite(changePath: string, basePath: string, outPath: string, maskPath: string, flags: ChangeAndMaskFlags | CompositeFlagsObj): ProcessPromise
Wrapper 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 |
gm.CompositeFlagsObj;
Options configuration for the gm.composite
function
Extends CommonFlagsObj
gm.ChangeAndMaskFlags;
If compositing with a mask, you can specify the change and mask flags separately
{
change?: CompositeFlagsObj;
mask?: CompositeFlagsObj;
}
gm.pipe(inPath: string, outPath: string, processes: ((pipeIn?: string, pipeOut?: string, index?: number) => ProcessPromise)[]): ProcessPromise
Pipe 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 |
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
gm.CommonFlagsObj;
Option configuration options that are common to both gm.convert
and gm.composite
gm.FlagsObj;
ConvertFlagsObj & CompositeFlagsObj
gm.channel;
'red' | 'green' | 'blue' | 'cyan' | 'magenta' | 'yellow' | 'black' | 'opacity' | 'gray' | 'matte'
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)[] |
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'
gm.utils.supportedFlags;
An object containing the supported flags and their types (or options).
gm.utils.GMCommand;
An internal string indictor for which gm command to use.
Only used in configuration for gm.utils.SupportedFlag
.
'convert' | 'composite'
gm.utils.SupportedFlag;
An internal configuration object for a supported flag.