Usage

import "https://deno.land/x/[email protected]/mod.ts";

Table of Contents

• Usage
• encoding
  • CSV
  • JSONC
  • JSON5
  • JsonStream
  • TOML
  • YAML
  • FrontMatter
  • base64
  • base64url
  • binary
  • Hex
• testing
  • all
  • asserts
  • bdd
  • mock
  • snapshot
  • chai
  • fc
• Examples
• Contributing

This project uses side-effect imports to extend the global namespace of the Deno runtime. It adds various tools from Deno Standard Library's encoding and testing suites.

For example, by importing ./encoding.ts, your project will have access to CSV, JSON5, YAML, and TOML modules (to name a few) at the global level. See all available API's below.

---

encoding

this/encoding exposes all the std/encoding modules from the Deno Standard Library, along with a few extra goodies too.

import "https://deno.land/x/[email protected]/encoding.ts";

CSV

import "https://deno.land/x/[email protected]/encoding/csv.ts";

.parse

CSV.parse(text: string, options?: CSV.ParseOptions): string[][];

CSV.parse(text: string, { columns?: CSV.Column[]; }): Record<string, unknown>;

.stringify

CSV.stringify(data: CSV.DataItem[], options?: CSV.StringifyOptions): string;

Source: [email protected]/encoding/csv.ts

JSONC

import "https://deno.land/x/[email protected]/encoding/jsonc.ts";

.parse

JSONC.parse(data: string, { allowTrailingComma?: boolean }): JsonValue;

.stringify

JSONC.stringify(data: JsonValue, replacer?: (key: string, value: any) => any, space?: string | number): string;

JSONC.stringify(data: JsonValue, replacer?: (string | number)[], space?: string | number): string;

Source: [email protected]/encoding/jsonc.ts

JSON5

import "https://deno.land/x/[email protected]/encoding/json5.ts";

.parse

JSON5.parse<T = JSONValue>(text: string, reviver?: JSONReviverFn): T;

.stringify

JSON5.stringify(data: JSONValue, replacer?: JSONReplacerFn, space?: string | number): string;

.require

JSON5.require<T = JSONValue>(path: string | URL, reviver?: JSONReviverFn): T;

.requireAsync

JSON5.require<T = JSONValue>(path: string | URL, reviver?: JSONReviverFn): Promise<T>;

JsonStream

import "https://deno.land/x/[email protected]/encoding/jsonstream.ts";

This is a custom implementation of the Deno Standard Library's JsonStream classes.

Importing jsonstream.ts creates a global named JsonStream with these properties:

.Parse

Shorthand alias for the JsonParseStream class.

Must be called with the new keyword before its constructor, like so:

const stream = new JsonStream.Parse(...options);

JsonParseStream Documentation

.Stringify

Shorthand alias for the JsonStringifyStream class.

Must be called with the new keyword before its constructor, like so:

const stream = new JsonStream.Stringify(...options);

JsonStringifyStream Documentation

.Concatenated

Shorthand alias for the ConcatenatedJsonParseStream class.

Must be called with the new keyword before its constructor, like so:

const stream = new JsonStream.Concatenated(...options);

ConcatenatedJsonParseStream Documentation

.useParse

Shorthand equivalent to calling new JsonStream.Parse(), this creates a new instance of the JsonParseStream class.

const stream = JsonStream.useParse(...options);

.useStringify

Shorthand equivalent to calling new JsonStream.Stringify(), this creates a new instance of the JsonStringifyStream class.

const stream = JsonStream.useStringify(...options);

.useConcat

Shorthand equivalent to calling new JsonStream.Concatenated(), this creates a new instance of the ConcatenatedJsonParseStream class.

const stream = JsonStream.useConcat(...options);

TOML

import "https://deno.land/x/[email protected]/encoding/toml.ts";

.parse

TOML.parse(text: string): Record<string, unknown>;

.stringify

TOML.stringify(data: Record<string, unknown>, options: TOML.FormatOptions): string;

Source: [email protected]/encoding/toml.ts

YAML

import "https://deno.land/x/[email protected]/encoding/yaml.ts";

.parse

YAML.parse(content: string, options?: LoaderStateOptions): unknown;

.parseAll

YAML.parseAll(content: string, options?: LoaderStateOptions): unknown;

YAML.parseAll(content: string, iterator: CbFunction, options?: LoaderStateOptions);

.stringify

YAML.stringify(obj: Record<string, unknown>, options?: DumperStateOptions): string;

Source: [email protected]/encoding/yaml.ts

FrontMatter

import "https://deno.land/x/[email protected]/encoding/front_matter.ts";

.extract

FrontMatter.extract<T = unknown>(str: string): Extract<T>;

type Extract<T> = {
  frontMatter: string;
  body: string;
  attrs: T;
}

.test

FrontMatter.test(markdown: string): boolean;

Source: [email protected]/encoding/front_matter.ts

---

base64

import "https://deno.land/x/[email protected]/encoding/base64.ts";

.encode

base64.encode(data: ArrayBuffer | string): string;

.decode

base64.decode(b64: string): string;

.decodeBytes

base64.decodeBytes(b64: string): Uint8Array;

Source: [email protected]/encoding/base64.ts

---

base64url

import "https://deno.land/x/[email protected]/encoding/base64url.ts";

.encode

base64.encode(data: BufferSource | string): string;

.decode

base64.decode(b64url: string): string;

.decodeBytes

base64.decodeBytes(b64url: string): Uint8Array;

Source: [email protected]/encoding/base64url.ts

binary

import "https://deno.land/x/[email protected]/encoding/binary.ts";

Source: [email protected]/encoding/binary.ts

Hex

import "https://deno.land/x/[email protected]/encoding/hex.ts";

.encode

Hex.encode(); // TODO

.decode

Hex.decode(); // TODO

Source: [email protected]/encoding/hex.ts

---

testing

import "https://deno.land/x/[email protected]/testing.ts";

Note: due to the size of chai and fc, they have been excluded from the imports in the ./testing.ts file. To use them, please import their respective files instead. Or, if you really want to YOLO, you can import all of the testing tools at once. See below.

all

import "https://deno.land/x/[email protected]/testing/all.ts";

Warning: this Imports everything below add quite a bit of weight to your project.

asserts

import "https://deno.land/x/[email protected]/testing/asserts.ts";

Source: [email protected]/testing/asserts.ts

---

bdd

import "https://deno.land/x/[email protected]/testing/bdd.ts";

beforeAll

let fixture: Set<number>;
let startTime: number, endTime: number;

beforeAll(() => {
  fixture = new Set([]);
  startTime = Date.now(); 
});

afterAll

afterAll(() => {
  fixture.clear();
  fixture = undefined;
  console.log
});

beforeEach

beforeEach(() => {
  fixture.clear();
  for (let i = 1; i <= 10; i++) fixture.add(i);
});

afterEach

afterEach(() => {
  fixture = new Set([1, 2, 3, 4]);
});

describe

it

Source: [email protected]/testing/bdd.ts

mock

import "https://deno.land/x/[email protected]/testing/mock.ts";

Source: [email protected]/testing/mock.ts

snapshot

import "https://deno.land/x/[email protected]/testing/snapshot.ts";

Source: [email protected]/testing/snapshot.ts

chai

import "https://deno.land/x/[email protected]/testing/chai.ts";

Source: [email protected]

fc (fastcheck)

import "https://deno.land/x/[email protected]/testing/fc.ts";

Source: [email protected]

---

examples

JSONC, JSON5, YAML, TOML

Now you can use CSV, JSON5, JSONC, YAML, TOML (and more), just as easily as you would use JavaScript's builtin JSON object. Check it out below.

import "https://deno.land/x/[email protected]/encoding.ts";

// deno.jsonc => { "compilerOptions": { "lib": ["deno.ns", "deno.window"] }, ... }
const deno_jsonc = JSONC.parse(await Deno.readTextFile("./deno.jsonc"));
// { compilerOptions: { lib: ["deno.ns", "deno.window"] }, ... }

const deno_json5 = JSON5.stringify(deno_jsonc);
// {compilerOptions:{lib:['deno.ns','deno.window']}, ... }

const deno_toml = TOML.stringify(deno_jsonc);
// [compilerOptions.lib] = ["deno.ns", "deno.window"]

const deno_yml = YAML.stringify(deno_jsonc);
// compilerOptions:
//   lib: [deno.ns, deno.window]

FrontMatter.extract

import "https://deno.land/x/[email protected]/testing/asserts.ts";
import "https://deno.land/x/[email protected]/encoding/front_matter.ts";

const { attrs, body, frontMatter } = FrontMatter.extract<{ title: string }>(
  "---\ntitle: Three dashes marks the spot\n---\n");

assertEquals(attrs.title, "Three dashes marks the spot");
assertEquals(body, "");
assertEquals(frontMatter, "title: Three dashes marks the spot");

describe + it

import "https://deno.land/x/[email protected]/testing/bdd.ts";

let users: Map<string, unknown>;

// globally available hooks! 
// (beforeAll, afterAll, beforeEach, afterEach)
beforeEach(() => {
  users = new Map<string, unknown>();
});

// behavior-driven development (bdd) testing API
describe("Users Map", () => {

  it("should initially empty", () => {
    assertEquals(users.size, 0);
  });

  it("should be readable and writable", () => {
    users.set("key", "value");
    assertEquals(users.size, 1);
    assertArrayIncludes([...users.values()], ["value"]);
  });

});

assertEquals + AssertionError

import "https://deno.land/x/[email protected]/testing/asserts.ts";

Deno.test("Global Assertions", async ({ step }) => {

  await step("are they equal?", () =>
    assertEquals(+new Date("1970-01-01T00:00:00.000Z"), 0);

  await step("AssertionError also available", () => {
    if (1 !== 1) {
      throw new AssertionError("OH NO! 1 != 1?!?! BAD JUJU")
    }
  });
});

chai (chai.js)

import "https://deno.land/x/[email protected]/testing/chai.ts";

fc

import "https://deno.land/x/[email protected]/testing/fc.ts";

---

Contributing

⚠️ Fixing a bug? Create an Issue first

Unless you're fixing a bug for which an issue already exists!

This allows the issue to be connected to your Pull Request, creating a permanent record of your contribution to the project. It also helps maintainers with tracking project progression.

Creating an issue also ensures you're given credit for fixing that bug. 😁

---

Fork + clone the repository

Note: This section assumes you have the GitHub CLI. You should get it.

gh repo fork deno911/this --clone

Create a new branch for your changes

git checkout -b fix/typo-in-readme

Make small changes and concise commits

# hack hack hack...

git commit README.md -m "fix: typos in README.md" && git push

Note: keep the scope of your changes relevant and concise.

Open a Pull Request

gh pr create --title "fix: typos in README.md"

Or just open your repo on GitHub.com and follow the prompts.

Warning: make sure you select the upstream repo for your PR!

---

🅓🅔🅝🅞⑨①①

The foundation of this module was inspired by ije/global.