swiss-zx (Swiss Army Knife for zx)

A collection of helper functions and useful little things for Google's zx

Uses swiss-ak

• Table of Contents
  • $$ (double dollar)
  • os
  • ffmpegTools
  • gm

Install

npm install swiss-zx

or

yarn add swiss-zx

$$ (double dollar)

• $$ (double dollar)
  • cd
  • pwd
  • ls
  • rm
  • mkdir
  • cp
  • mv
  • touch
  • cat
  • grep
  • find
    • FindOptions
    • FindType
  • findDirs
  • findFiles
  • findModified
    • ModifiedFile
  • lastModified
  • rsync
  • sync
  • isFileExist
  • isDirExist
  • readFile
  • writeFile
  • readJSON
  • writeJSON
  • pipe
  • exiftool
    • ExifToolAttributesObj
    • ExifToolAttributes
  • utils
    • intoLines

cd

$$.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 |

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> |

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[]> |

rm

$$.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 |

mkdir

$$.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 |

cp

$$.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 |

mv

$$.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 |

touch

$$.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 |

cat

$$.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 |

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[]> |

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[]> |

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 |

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 |

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[]> |

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[]> |

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[]> |

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'
}

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> |

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> |

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> |

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> |

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> |

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> |

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> |

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> |

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> |

pipe

$$.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 |

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> |

ExifToolAttributesObj

$$.ExifToolAttributesObj;

Interface for the attributes returned by exiftool

ExifToolAttributes

$$.ExifToolAttributes;

Type for the names of the attributes returned by exiftool

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[] |

os

• os
  • closeFinder

closeFinder

closeFinder(): Promise<void>
os.closeFinder(): Promise<void>

Close all Mac OS X Finder windows.

await closeFinder();

| Return Type | |-----------------| | Promise<void> |

ffmpegTools

• ffmpegTools
  • ffmpeg
  • toFFmpegTimeFormat
  • getProbe
    • ProbeResult
  • getProbeValue
  • getTotalFrames

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): 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 |

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

• gm
  • convert
    • ConvertFlagsObj
  • composite
    • CompositeFlagsObj
    • ChangeAndMaskFlags
  • pipe
  • PIPE
  • Types
    • CommonFlagsObj
    • FlagsObj
    • channel
  • utils
    • flagsObjToArray
    • channelComposeCopyMap
    • supportedFlags
      • GMCommand
      • SupportedFlag

convert

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 |

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): 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 |

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)[]): 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 |

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.