swiss-zx
TypeScript icon, indicating that this package has built-in type declarations

2.0.1 • Public • Published

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

or

yarn add swiss-zx

$$ (double dollar)

[↑ Back to top ↑]

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

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

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

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

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

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

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

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

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

[↑ Back to top ↑]

closeFinder

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

Close all Mac OS X Finder windows.

await closeFinder();
Return Type
Promise<void>

[↑ Back to os ↑]

ffmpegTools

[↑ Back to top ↑]

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>

[↑ Back to ffmpegTools ↑]

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

[↑ Back to ffmpegTools ↑]

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>

[↑ Back to ffmpegTools ↑]

ProbeResult

ffmpegTools.ProbeResult;

Note: this interface is a guide, and other properties may exist, and some may be have different types

[↑ Back to ffmpegTools ↑]

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>

[↑ Back to ffmpegTools ↑]

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>

[↑ Back to ffmpegTools ↑]

gm

[↑ Back to top ↑]

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

[↑ Back to gm ↑]

ConvertFlagsObj

gm.ConvertFlagsObj;

Options configuration for the gm.convert function

Extends CommonFlagsObj

[↑ Back to gm ↑]

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

[↑ Back to gm ↑]

CompositeFlagsObj

gm.CompositeFlagsObj;

Options configuration for the gm.composite function

Extends CommonFlagsObj

[↑ Back to gm ↑]

ChangeAndMaskFlags

gm.ChangeAndMaskFlags;

If compositing with a mask, you can specify the change and mask flags separately

{
  change?: CompositeFlagsObj;
  mask?: CompositeFlagsObj;
}

[↑ Back to gm ↑]

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

[↑ Back to gm ↑]

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

[↑ Back to gm ↑]

Types

CommonFlagsObj

gm.CommonFlagsObj;

Option configuration options that are common to both gm.convert and gm.composite

[↑ Back to gm ↑]

FlagsObj

gm.FlagsObj;

ConvertFlagsObj & CompositeFlagsObj

[↑ Back to gm ↑]

channel

gm.channel;

'red' | 'green' | 'blue' | 'cyan' | 'magenta' | 'yellow' | 'black' | 'opacity' | 'gray' | 'matte'

[↑ Back to gm ↑]

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

[↑ Back to gm ↑]

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'

[↑ Back to gm ↑]

supportedFlags

gm.utils.supportedFlags;

An object containing the supported flags and their types (or options).

[↑ Back to gm ↑]

GMCommand
gm.utils.GMCommand;

An internal string indictor for which gm command to use.

Only used in configuration for gm.utils.SupportedFlag.

'convert' | 'composite'

[↑ Back to gm ↑]

SupportedFlag
gm.utils.SupportedFlag;

An internal configuration object for a supported flag.

[↑ Back to gm ↑]

Readme

Keywords

none

Package Sidebar

Install

npm i swiss-zx

Weekly Downloads

14

Version

2.0.1

License

MIT

Unpacked Size

192 kB

Total Files

27

Last publish

Collaborators

  • jackcannon