Skip to main content

abstruct

deno land deno doc GitHub release (latest by date) codecov GitHub

test NPM

Abstract structure for JavaScript data validation

Abstruct(not abstract!) provides features for defining data structures. It used for any operation. For example, validation.

Usage

Define the data structure and validate.

import {
  and,
  assert,
  maxCount,
  pattern,
  props,
  string,
  validDate,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

const Id = and(string, pattern(/^\d$/));
const Book = props({
  id: Id,
  title: maxCount(256).expect(`length should be less than or equal to 256`),
  publishAt: validDate,
});

assertThrows(() =>
  assert(Book, {
    id: 0,
    title: "Harry Potter and the Philosopher's Stone",
    publishAt: new Date("1997/6/26"),
  })
);

Validators do only one thing, so they can be combined to make new validator.

import {
  and,
  gte,
  int,
  lte,
  validate,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";

const Int8 = and(
  int,
  gte(-127),
  lte(128),
);
declare const input: number;

const result = validate(Int8, input);

if (result.isOk()) {
  // result.value;
} else {
  // result.value;
}

And narrowing works correctly.

import {
  and,
  assert,
  gte,
  instance,
  lte,
  validDate,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
import { Assert, IsExact } from "https://deno.land/std/testing/types.ts";

const ValidDate = and(
  instance(Date),
  validDate,
  gte(new Date("1970/1/1")),
  lte(new Date("2038/1/19")),
);
const input: unknown = null;

assert(ValidDate, input);

type doTest = Assert<IsExact<typeof input, Date>, true>;

Fully customizable messages:

import { int8, string } from "https://deno.land/x/abstruct@$VERSION/mod.ts";

const Int8 = int8.expect("should be int8!!!");
const ID = string.expect(({ input }) =>
  `id should be string, actual ${typeof input}`
);

Philosophy

  1. Composable: All features are composable. Being composable brings the following features:

    • Single responsibility
    • DRY
    • Pay as you go
    • Customizable
    • Tiny
  2. Library first: It can use in library. To fulfill this, special attention has been paid to the following:

    • Universal
    • Customizable
    • Tiny
  3. Type first: Type safety is a matter of course.

Documentation

You have very little to learn.

Example

Few examples of common patterns:

Inspired by

License

Copyright © 2023-present Tomoki Miyauci.

Released under the MIT license