feat(tar/unstable): @std/tar (#5905)

* feat(tar/unstable): `@std/tar`

* fix

* edit

_tools/check_circular_package_dependencies.ts

@@ -67,6 +67,7 @@ type Mod =
   | "regexp"
   | "semver"
   | "streams"
+  | "tar"
   | "testing"
   | "text"
   | "toml"
@@ -109,6 +110,7 @@ const ENTRYPOINTS: Record<Mod, string[]> = {
   regexp: ["mod.ts"],
   semver: ["mod.ts"],
   streams: ["mod.ts"],
+  tar: ["mod.ts"],
   testing: ["bdd.ts", "mock.ts", "snapshot.ts", "time.ts", "types.ts"],
   text: ["mod.ts"],
   toml: ["mod.ts"],

_tools/check_docs.ts

@@ -65,6 +65,7 @@ const ENTRY_POINTS = [
   "../regexp/mod.ts",
   "../semver/mod.ts",
   "../streams/mod.ts",
+  "../tar/mod.ts",
   "../text/mod.ts",
   "../testing/bdd.ts",
   "../testing/mock.ts",

archive/deno.json

@@ -3,9 +3,7 @@
   "version": "0.225.1",
   "exports": {
     ".": "./mod.ts",
-    "./tar-stream": "./tar_stream.ts",
     "./tar": "./tar.ts",
-    "./untar-stream": "./untar_stream.ts",
     "./untar": "./untar.ts"
   }
 }

archive/mod.ts

@@ -68,5 +68,3 @@
  */
 export * from "./tar.ts";
 export * from "./untar.ts";
-export * from "./tar_stream.ts";
-export * from "./untar_stream.ts";

browser-compat.tsconfig.json

@@ -39,6 +39,7 @@
     "./regexp",
     "./semver",
     "./streams",
+    "./tar",
     "./testing",
     "./text",
     "./toml",

deno.json

@@ -80,6 +80,7 @@
     "./regexp",
     "./semver",
     "./streams",
+    "./tar",
     "./testing",
     "./text",
     "./toml",

import_map.json

@@ -38,6 +38,7 @@
     "@std/regexp": "jsr:@std/regexp@^1.0.0",
     "@std/semver": "jsr:@std/semver@^1.0.2",
     "@std/streams": "jsr:@std/streams@^1.0.3",
+    "@std/tar": "jsr:@std/tar@^0.1.0",
     "@std/testing": "jsr:@std/testing@^1.0.1",
     "@std/text": "jsr:@std/text@^1.0.4",
     "@std/toml": "jsr:@std/toml@^1.0.1",

tar/deno.json

@@ -0,0 +1,9 @@
+{
+  "name": "@std/tar",
+  "version": "0.1.0",
+  "exports": {
+    ".": "./mod.ts",
+    "./tar-stream": "./tar_stream.ts",
+    "./untar-stream": "./untar_stream.ts"
+  }
+}

tar/mod.ts

@@ -0,0 +1,29 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+/**
+ * Streaming utilities for working with tar archives.
+ *
+ * Files are not compressed, only collected into the archive.
+ *
+ * ```ts no-eval
+ * import { UntarStream } from "@std/tar/untar-stream";
+ * import { dirname, normalize } from "@std/path";
+ *
+ * for await (
+ *   const entry of (await Deno.open("./out.tar.gz"))
+ *     .readable
+ *     .pipeThrough(new DecompressionStream("gzip"))
+ *     .pipeThrough(new UntarStream())
+ * ) {
+ *   const path = normalize(entry.path);
+ *   await Deno.mkdir(dirname(path));
+ *   await entry.readable?.pipeTo((await Deno.create(path)).writable);
+ * }
+ * ```
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @module
+ */
+export * from "./tar_stream.ts";
+export * from "./untar_stream.ts";

tar/tar_stream.ts

@@ -139,7 +139,7 @@ const SLASH_CODE_POINT = "/".charCodeAt(0);
  *
  * @example Usage
  * ```ts no-eval
- * import { TarStream, type TarStreamInput } from "@std/archive/tar-stream";
+ * import { TarStream, type TarStreamInput } from "@std/tar/tar-stream";
  *
  * await ReadableStream.from<TarStreamInput>([
  *   {
@@ -302,7 +302,7 @@ export class TarStream implements TransformStream<TarStreamInput, Uint8Array> {
    *
    * @example Usage
    * ```ts no-eval
-   * import { TarStream } from "@std/archive/tar-stream";
+   * import { TarStream } from "@std/tar/tar-stream";
    *
    * await ReadableStream.from([
    *   {
@@ -338,7 +338,7 @@ export class TarStream implements TransformStream<TarStreamInput, Uint8Array> {
    *
    * @example Usage
    * ```ts no-eval
-   * import { TarStream } from "@std/archive/tar-stream";
+   * import { TarStream } from "@std/tar/tar-stream";
    *
    * await ReadableStream.from([
    *   {
@@ -427,7 +427,7 @@ function parsePath(
  *
  * @example Usage
  * ```ts no-assert no-eval
- * import { assertValidPath, TarStream, type TarStreamInput } from "@std/archive";
+ * import { assertValidPath, TarStream, type TarStreamInput } from "@std/tar";
  *
  * const paths = (await Array.fromAsync(Deno.readDir("./")))
  *   .filter(entry => entry.isFile)
@@ -475,7 +475,7 @@ export function assertValidPath(path: string) {
  *
  * @example Usage
  * ```ts no-assert no-eval
- * import { assertValidTarStreamOptions, TarStream, type TarStreamInput } from "@std/archive";
+ * import { assertValidTarStreamOptions, TarStream, type TarStreamInput } from "@std/tar";
  *
  *  const paths = (await Array.fromAsync(Deno.readDir('./')))
  *   .filter(entry => entry.isFile)

tar/untar_stream.ts

@@ -157,7 +157,7 @@ export interface TarStreamEntry {
  *
  * @example Usage
  * ```ts no-eval
- * import { UntarStream } from "@std/archive/untar-stream";
+ * import { UntarStream } from "@std/tar/untar-stream";
  * import { dirname, normalize } from "@std/path";
  *
  * for await (
@@ -341,7 +341,7 @@ export class UntarStream
    *
    * @example Usage
    * ```ts no-eval
-   * import { UntarStream } from "@std/archive/untar-stream";
+   * import { UntarStream } from "@std/tar/untar-stream";
    * import { dirname, normalize } from "@std/path";
    *
    * for await (
@@ -367,7 +367,7 @@ export class UntarStream
    *
    * @example Usage
    * ```ts no-eval
-   * import { UntarStream } from "@std/archive/untar-stream";
+   * import { UntarStream } from "@std/tar/untar-stream";
    * import { dirname, normalize } from "@std/path";
    *
    * for await (