dependency maintenance; rewrote build in typescript; added first shor…

…t-form run functions

README.md

@@ -36,10 +36,12 @@ behaviors for your data. It also lets you customize `stderr` and error handling.
 With just a little code for definition, you can work with bytes or text,
 synchronous or asynchronous, buffered or unbuffered.
 
-#### An Example
+### An Example
 
-To get you started, here is a simple example where we pass a text `string` to a
+To get you started, here is an example where we pass a text `string` to a
 process and get back a `Uint8Array` - text compressed to bytes using `gzip`.
+This uses the "short-form" function that takes a string as input and returns a
+`Uint8array` as output.
 
 ```ts
 /**
@@ -48,15 +50,18 @@ process and get back a `Uint8Array` - text compressed to bytes using `gzip`.
  * @return The text compressed into bytes.
  */
 async function gzip(text: string): Promise<Uint8Array> {
-  return await runner(stringInput(), bytesOutput())().run({
-    cmd: ["gzip", "-c"],
-  }, text);
+  return await proc.runSB({ cmd: ["gzip", "-c"] }, text);
 }
 
 console.dir(await gzip("Hello, world."));
 /* prints an array of bytes to console. */
 ```
 
+> ℹ️ **Short Form** The short form run functions are new. It seems a little odd
+> to have so many different typed functions, but it cuts out a lot of
+> boilerplate. This feature will most likely be under development for some time.
+> See [runner.ts](./runner.ts) for available short form run functions.
+
 ## Input Types
 
 | Name                                  | Description                                                  |
@@ -146,12 +151,12 @@ manually).
 
 Most of the time, `proc` can automatically clean up processes. In some cases
 where the output of one process feeds into the input of another, the first
-process won't be fully processed and therefore cannot be automatically shut
-down. This can also happen if you don't fully process `AsyncIterable` output of
-a process. This will result in resource leakage. If your program is short and
-does not start many processes, or if you are sure that the way you are using
-processes is well behaved (either non-streaming output or all output data is
-fully consumed), you can use the short form safely.
+process's output won't be fully read, and therefore the process cannot be
+automatically shut down. This can also happen if you don't fully process
+`AsyncIterable` output of a process. This will result in resource leakage. If
+your program is short and does not start many processes, or if you are sure that
+the way you are using processes is well behaved (either non-streaming output or
+all output data is fully consumed), you can use the short form safely.
 
 ### Direct Control Over `stderr`
 

build.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env -S deno run --quiet --allow-run
+
+import * as proc from "./mod.ts";
+import { dirname } from "./runners/utility.ts";
+
+async function findAllTypescriptFiles(): Promise<string[]> {
+  return await proc.run0Sa(
+    { cmd: ["find", dirname(import.meta), "-name", "*.ts"] },
+  );
+}
+
+async function updateDependencies(): Promise<void> {
+  await proc.run00({ cmd: ["udd", ...(await findAllTypescriptFiles())] });
+}
+
+async function format(): Promise<void> {
+  await proc.run00({ cmd: ["deno", "fmt", dirname(import.meta)] });
+
+  /* Fix breaks to legacy shebang caused by deno formatter. */
+  await proc.run00(
+    {
+      cmd: [
+        "sed",
+        "-i",
+        '2s|^":";\\s[/][/]#;|":" //#;|',
+        ...(await findAllTypescriptFiles()),
+      ],
+    },
+  );
+}
+
+async function lint(): Promise<void> {
+  await proc.run00({ cmd: ["deno", "lint", dirname(import.meta)] });
+}
+
+async function test(): Promise<void> {
+  await proc.run00({
+    cmd: ["deno", "test", "--allow-run", "--reload", dirname(import.meta)],
+  });
+}
+
+await updateDependencies();
+await format();
+await lint();
+await test();

deps-test.ts

@@ -1,3 +1,3 @@
-export * from "https://deno.land/std@0.125.0/testing/asserts.ts";
+export * from "https://deno.land/std@0.126.0/testing/asserts.ts";
 export * from "https://deno.land/x/[email protected]/mod.ts";
-export * from "https://deno.land/std@0.125.0/fmt/colors.ts";
+export * from "https://deno.land/std@0.126.0/fmt/colors.ts";

deps.ts

@@ -1,3 +1,3 @@
-export * from "https://deno.land/std@0.125.0/textproto/mod.ts";
-export * from "https://deno.land/std@0.125.0/async/mod.ts";
-export * from "https://deno.land/std@0.125.0/io/mod.ts";
+export * from "https://deno.land/std@0.126.0/textproto/mod.ts";
+export * from "https://deno.land/std@0.126.0/async/mod.ts";
+export * from "https://deno.land/std@0.126.0/io/mod.ts";

examples/pushiterable/example-of-pushiterable.ts

@@ -3,7 +3,7 @@
 import { Answer, Question } from "./common-json-defs.ts";
 import * as proc from "../../mod.ts";
 import { asynciter } from "https://deno.land/x/[email protected]/mod.ts";
-import { blue, red } from "https://deno.land/std@0.125.0/fmt/colors.ts";
+import { blue, red } from "https://deno.land/std@0.126.0/fmt/colors.ts";
 
 /**
  * This demonstrates sending objects to and receiving objects from a child process

run-examples.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env -S deno run --quiet --allow-run
+
+import * as proc from "./mod.ts";
+import { dirname } from "./runners/utility.ts";
+
+const here = dirname(import.meta);
+
+proc.run00({
+  cmd: [
+    "bash",
+    "--login",
+    "-c",
+    `
+set -e
+
+cd "${here}/examples/warandpeace" && (
+  set -x
+  time ./countwords.sh < ./warandpeace.txt.gz
+  time ./countwords.ts < ./warandpeace.txt.gz
+  time ./countwords2.ts < ./warandpeace.txt.gz
+  echo "a b c d" | ./countwords2.ts || true
+  time ./countwords3.ts < ./warandpeace.txt.gz
+  echo "a b c d" | ./countwords3.ts || true
+)
+
+cd "${here}/examples/pushiterable" && (
+  PATH=".:$PATH" ./example-of-pushiterable.ts
+)
+
+cd "${here}/examples/sounds" && (
+  ./sounds.ts
+)
+`,
+  ],
+});

runner.ts

@@ -1,5 +1,8 @@
 import { RunnerImpl } from "./runner-impl.ts";
+import { bytesInput, bytesOutput } from "./runners/handlers/bytes.ts";
 import { emptyInput, emptyOutput } from "./runners/handlers/empty.ts";
+import { stringInput, stringOutput } from "./runners/handlers/string.ts";
+import { stringArrayOutput } from "./runners/handlers/string-array.ts";
 import {
   Group,
   group,
@@ -40,10 +43,63 @@ export function runner<A, B>(
 }
 
 /**
- * A simple runner. `stdin` is empty. `stdout` and `stderr` are directed to the parent.
- * Note that `stdout` is treated is assumed to be text and not byte data.
- * @returns A process runner.
+ * A simple runner.
+ * - `stdin` is empty.
+ * - `stdout` and `stderr` are redirected to the parent.
+ * - the global group is used.
+ */
+export async function run00(options: RunOptions): Promise<void> {
+  await new RunnerImpl(globalGroup, emptyInput(), emptyOutput()).run(
+    options,
+  );
+}
+
+/**
+ * A non-streaming runner for `string[]` output.
+ * - `stdout` is interpreted as lines of text and returned as a `string[]`.
+ * - `stdin` is empty.
+ * - `stderr` is redirected to the parent.
+ * - the global group is used.
+ */
+export async function run0Sa(options: RunOptions): Promise<string[]> {
+  return await new RunnerImpl(globalGroup, emptyInput(), stringArrayOutput())
+    .run(
+      options,
+    );
+}
+
+/**
+ * A non-streaming runner for `Uint8Array` input and `string` output.
+ * - `stdout` is interpreted as a `string`.
+ * - `stdin` is interpreted as a `Uint8Array`.
+ * - `stderr` is redirected to the parent.
+ * - the global group is used.
+ */
+export async function runBS(
+  options: RunOptions,
+  input: Uint8Array,
+): Promise<string> {
+  return await new RunnerImpl(globalGroup, bytesInput(), stringOutput())
+    .run(
+      options,
+      input,
+    );
+}
+
+/**
+ * A non-streaming runner for `string`input and `Uint8Array` output.
+ * - `stdout` is interpreted as a `Uint8Array`.
+ * - `stdin` is interpreted as a `string`.
+ * - `stderr` is redirected to the parent.
+ * - the global group is used.
  */
-export function simpleRunner(group?: Group): Runner<void, void> {
-  return new RunnerImpl(group || globalGroup, emptyInput(), emptyOutput());
+export async function runSB(
+  options: RunOptions,
+  input: string,
+): Promise<Uint8Array> {
+  return await new RunnerImpl(globalGroup, stringInput(), bytesOutput())
+    .run(
+      options,
+      input,
+    );
 }

runners/constants.ts

@@ -1,4 +1,4 @@
-import { isWindows } from "https://deno.land/std@0.125.0/_util/os.ts";
+import { isWindows } from "https://deno.land/std@0.126.0/_util/os.ts";
 
 export const LINESEP: string = (() => {
   if (isWindows) {

runners/handlers/bytes.test.ts

@@ -1,4 +1,4 @@
-import { assertEquals } from "https://deno.land/std@0.125.0/testing/asserts.ts";
+import { assertEquals } from "https://deno.land/std@0.126.0/testing/asserts.ts";
 import * as proc from "../../mod.ts";
 
 Deno.test({

runners/handlers/empty-handlers.ts

@@ -6,7 +6,7 @@ import {
 import { ErrorHandler } from "../error-support.ts";
 import { InputHandler } from "../proc-group.ts";
 import { StderrProcessor } from "../stderr-support.ts";
-import { AbstractTextUnbufferedOutputHandler } from "./abstract-handlers.ts";
+import { AbstractBytesUnbufferedOutputHandler } from "./abstract-handlers.ts";
 
 /**
  * Empty `stdin`.
@@ -26,7 +26,7 @@ export class EmptyInputHandler implements InputHandler<void> {
  * Write lines of `stdout` to `stdout` of the parent process, unbuffered.
  */
 export class EmptyOutputHandler
-  extends AbstractTextUnbufferedOutputHandler<void> {
+  extends AbstractBytesUnbufferedOutputHandler<void> {
   constructor(
     processStderr: StderrProcessor,
     errorHandler: ErrorHandler,
@@ -40,8 +40,8 @@ export class EmptyOutputHandler
     process: MultiCloseProcess,
     input: { stdin: MultiCloseWriter; handlerResult: Promise<null | Error> },
   ): Promise<void> {
-    for await (const line of this.process(stdout, stderr, process, input)) {
-      console.log(line);
+    for await (const bytes of this.process(stdout, stderr, process, input)) {
+      Deno.stdout.writeSync(bytes);
     }
   }
 }

runners/handlers/empty.test.ts

@@ -7,7 +7,7 @@ Deno.test(
       async function say(text: string): Promise<void> {
         const pg = proc.group();
         try {
-          await proc.simpleRunner(pg).run({
+          await proc.run00({
             cmd: [
               "spd-say",
               "-w",

runners/utility.ts

@@ -1,4 +1,5 @@
 import { BufReader, BufWriter } from "../deps.ts";
+import * as path from "https://deno.land/[email protected]/path/mod.ts";
 
 export const DEFAULT_BUFFER_SIZE = 4096;
 
@@ -207,3 +208,11 @@ export async function sleep(delayms: number): Promise<void> {
     setTimeout(() => resolve(), delayms)
   );
 }
+
+export function filename(meta: { url: string }): string {
+  return path.fromFileUrl(meta.url);
+}
+
+export function dirname(meta: { url: string }): string {
+  return path.dirname(filename(meta));
+}

tests/proc.readme.test.ts

@@ -7,6 +7,7 @@ import {
   stringInput,
   stringOutput,
 } from "../mod.ts";
+import * as proc from "../mod.ts";
 
 Deno.test({
   name: "[README] Key Concepts | Leaking Resources",
@@ -54,6 +55,22 @@ Deno.test({
   },
 });
 
+Deno.test({
+  name: "[README] Input and Output Types (Short Form)",
+  async fn() {
+    /**
+     * Use `gzip` to compress some text.
+     * @param text The text to compress.
+     * @return The text compressed into bytes.
+     */
+    async function gzip(text: string): Promise<Uint8Array> {
+      return await proc.runSB({ cmd: ["gzip", "-c"] }, text);
+    }
+
+    console.dir(await gzip("Hello, world."));
+  },
+});
+
 Deno.test({
   name: "[README] Examples | Run an Inline Bash Script",
   async fn() {