swiss-zx v2.0.1

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'

pwd

$$.pwd(): Promise<string>

Get the current working directory

await $$.pwd(); // '/Users/username'
await $$.cd('./some/folder');
await $$.pwd(); // '/Users/username/some/folder'

ls

$$.ls(dir: string, flags: string[]): Promise<string[]>

Wrapper for ls (list) command

await $$.ls('example') // ['a', 'b']

rm

$$.rm(item: string): ProcessPromise

Wrapper for rm (remove) command

await $$.rm('example') // same as $`rm -rf 'example'`

mkdir

$$.mkdir(item: string): ProcessPromise

Wrapper for mkdir (make directory) command

await $$.mkdir('example') // same as $`mkdir -p 'example'`

cp

$$.cp(a: string, b: string): ProcessPromise

Wrapper for cp (copy) command

await $$.cp('example1', 'example2') // same as $`cp -r 'example1' 'example2'`

mv

$$.mv(a: string, b: string): ProcessPromise

Wrapper for mv (move) command

await $$.mv('example1', 'example2') // same as $`mv 'example1' 'example2'`

touch

$$.touch(item: string): ProcessPromise

Wrapper for touch (create blank file) command

await $$.touch('example') // same as $`touch 'example'`

cat

$$.cat(item: string): ProcessPromise

Wrapper for cat (concatenate) command

await $$.cat('example') // same as $`cat 'example'`

grep

$$.grep(pattern: string, file: string): Promise<string[]>

Wrapper for grep (Global Regular Expression Print) command

await $$.grep('example', '.') // same as $`grep 'example' '.'`

find

$$.find(dir: string, options: FindOptions): Promise<string[]>

Helper function for finding files

await $$.find('.', { type: 'f' }) // ['a', 'b']

FindOptions

$$.FindOptions;

Options for $$.find (and related other tools)

FindType

$$.FindType;

Type of item to find

findDirs

$$.findDirs(dir: string, options: FindOptions): Promise<string[]>

Find all directories in a given directory (shallow)

await $$.findDirs('.') // ['a', 'b']

findFiles

$$.findFiles(dir: string, options: FindOptions): Promise<string[]>

Find all files in a given directory (shallow)

await $$.findFiles('.') // ['a', 'b']

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

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

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

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`

isFileExist

$$.isFileExist(file: string): Promise<boolean>

Check if a file exists

await $$.isFileExist('example') // true

isDirExist

$$.isDirExist(dir: string): Promise<boolean>

Check if a directory exists

await $$.isDirExist('example') // true

readFile

$$.readFile(filepath: string): Promise<string>

Read a file's contents

await $$.readFile('example') // 'hello world'

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'

readJSON

$$.readJSON<T>(filepath: string): Promise<T>

Read a JSON file

await $$.readJSON('example.json') // { hello: 'world' }

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

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)
]);

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');

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

os

• os
  • closeFinder

closeFinder

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

Close all Mac OS X Finder windows.

await closeFinder();

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

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'

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, ... }

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'

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)

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, {});

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, {});

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)
]);

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

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.