Skip to content

Latest commit

 

History

History
642 lines (426 loc) · 13.9 KB

README.md

File metadata and controls

642 lines (426 loc) · 13.9 KB
Raw

deno911/this

Usage

import "https://deno.land/x/this@0.160.1/mod.ts";
Table of Contents

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/this@0.160.1/encoding.ts";

CSV

import "https://deno.land/x/this@0.160.1/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: std@0.160.0/encoding/csv.ts

JSONC

import "https://deno.land/x/this@0.160.1/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: std@0.160.0/encoding/jsonc.ts

JSON5

import "https://deno.land/x/this@0.160.1/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/this@0.160.1/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/this@0.160.1/encoding/toml.ts";

.parse

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

.stringify

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

Source: std@0.160.0/encoding/toml.ts

YAML

import "https://deno.land/x/this@0.160.1/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: std@0.160.0/encoding/yaml.ts

FrontMatter

import "https://deno.land/x/this@0.160.1/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: std@0.160.0/encoding/front_matter.ts

base64

import "https://deno.land/x/this@0.160.1/encoding/base64.ts";

.encode

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

.decode

base64.decode(b64: string): string;

.decodeBytes

base64.decodeBytes(b64: string): Uint8Array;

Source: std@0.160.0/encoding/base64.ts

base64url

import "https://deno.land/x/this@0.160.1/encoding/base64url.ts";

.encode

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

.decode

base64.decode(b64url: string): string;

.decodeBytes

base64.decodeBytes(b64url: string): Uint8Array;

Source: std@0.160.0/encoding/base64url.ts

binary

import "https://deno.land/x/this@0.160.1/encoding/binary.ts";

Source: std@0.160.0/encoding/binary.ts

Hex

import "https://deno.land/x/this@0.160.1/encoding/hex.ts";

.encode

Hex.encode(); // TODO

.decode

Hex.decode(); // TODO

Source: std@0.160.0/encoding/hex.ts

testing

import "https://deno.land/x/this@0.160.1/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/this@0.160.1/testing/all.ts";

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

asserts

import "https://deno.land/x/this@0.160.1/testing/asserts.ts";

Source: std@0.160.0/testing/asserts.ts

bdd

import "https://deno.land/x/this@0.160.1/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: std@0.160.0/testing/bdd.ts

mock

import "https://deno.land/x/this@0.160.1/testing/mock.ts";

Source: std@0.160.0/testing/mock.ts

snapshot

import "https://deno.land/x/this@0.160.1/testing/snapshot.ts";

Source: std@0.160.0/testing/snapshot.ts

chai

import "https://deno.land/x/this@0.160.1/testing/chai.ts";

Source: chai@4.3.4

fc (fastcheck)

import "https://deno.land/x/this@0.160.1/testing/fc.ts";

Source: fast-check@3.2.0

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/this@0.160.1/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/this@0.160.1/testing/asserts.ts";
import "https://deno.land/x/this@0.160.1/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/this@0.160.1/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/this@0.160.1/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/this@0.160.1/testing/chai.ts";

fc

import "https://deno.land/x/this@0.160.1/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.