spawn-tag
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    spawn-tag

    standard-readme compliant TODO: Put more badges here.

    A template tag that safely runs commands for you

    spawn-tag allows you to safely run terminal commands while including user input. Instead of using escaping techniques, it uses Node.js’s spawn API to pass arguments directly to the target command without using a shell to handle parsing.

    Table of Contents

    Security

    Although the method used in this module should be secure, please email me (address is in my profile) or contact me via Keybase (I’m j_f) if you find a security issue. Please do not open an issue as this would reveal the security issue I can implement and release a fix.

    Install

    npm install spawn-tag
    # or: 
    yarn add spawn-tag

    Usage

    Import the library:

    import spawn from 'spawn-tag'
    // or:
    import { spawn } from 'spawn-tag'
    // or, if you’re using CommonJS still:
    const { spawn } = require('spawn-tag')
    const message = 'Hello, world!'
    await spawn`echo ${message}`
    // => { stdout: 'Hello, world!\n', stderr: '', code: 0, signal: null }

    If you don’t need to keep the output, use .silently to avoid capturing it and save memory.

    await spawn.silently`rm -r node_modules`
    // => { stdout: null, stderr: null, code: 0, signal: null }

    If you want to customize encodings or other options passed to spawn, pass an object:

    await spawn({
      env: { ...process.env, MESSAGE: message },
    })`node -e 'console.log(process.env.MESSAGE)'`
    // => { stdout: 'Hello, world!\n', stderr: '', code: 0, signal: null }

    Important: Since spawn-tag does not use a shell, things like $VAR or ~ won’t resolve themselves.

    spawn can also give you buffers for stdout/stderr:

    await spawn({ capture: { stdout: true } })`echo ${message}`
    // => { stdout: <Buffer 48 65 6c 6c 6f 2c 20 77 6f 72 6c 64 21 0a>, stderr: null, code: 0, signal: null }

    The Promise-like object returned from spawn has a childProcess property that contains the actual ChildProcess object if you need to interact with it.

    API

    // Either of these will work:
    import spawn, { spawn } from 'spawn-tag'
     
    // Same with these:
    import { spawnSilently, silently } from 'spawn-tag'
    const { silently } = spawn
     
    // if you use TypeScript
    import { Options } from 'spawn-tag'
    interface Result {
      // string by default or if you pass an encoding
      // Buffer if you pass `true`
      // null if you pass `false` or use `.silently`
      stdout: string | Buffer | null
      stderr: string | Buffer | null
      code: number
      signal: string | null
    }
     
    interface PromiseLike extends Promise<Result> {
      childProcess: ChildProcess
    }
     
    declare const silently:
      | TemplateTag<PromiseLike>
      | ((options: Options) => TemplateTag<PromiseLike>)
     
    declare const spawn: { silently: typeof silently } & (
      | TemplateTag<PromiseLike>
      | ((options: Options) => TemplateTag<PromiseLike>))

    Maintainers

    @j-f1

    Contribute

    PRs accepted.

    Small note: If editing the README, please conform to the standard-readme specification.

    License

    MIT © 2018 Jed Fox

    Keywords

    none

    Install

    npm i spawn-tag

    DownloadsWeekly Downloads

    3

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    10.4 kB

    Total Files

    7

    Last publish

    Collaborators

    • j-f