npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

maas-schemas

v26.0.0

Published

Schemas for MaaS infrastructure

Downloads

17,373

Readme

MaaS-schemas submodule

Build Status

This repository contains the JSON schemas used by MaaS.

Features

  • Ajv compatible JSON Schemas
  • io-ts codecs for TypeScript

JavaScript API

The schemas can be used together with Ajv as follows.

Validate an object by first resolving the corresponding schema by schemaId NOTE: It is recommended to use schema $id instead of raw schema object

import * as mjsv from 'maasglobal-json-schema-validator';
import registry from 'maas-schemas/lib/ajv/registry';

const validator = mjsv.validator([registry]);

const phone = validator.validate(
  'https://schemas.maas.global/core/components/common.json#/definitions/phone',
  '+358401234567',
);

TypeScript API

The repostory also contains io-ts codecs that match the JSON Schema definitions. The TypeScript validators should work with any JavaScript compatible code but have the added benefit of producing an output type that match the schema as closely as possible.

Runtime Input Validation

In this basic use example we show how to use the codecs together with the io-ts-validator. The four alternative decode calls are alternative ways suiting different control flow and error handling models. The validator also contains matching encode calls for converting a decoded booking back to raw json.

import { validator } from 'io-ts-validator';
import Booking from 'maas-schemas/lib/io-ts/core/booking';

validator(Booking).decodeSync(json);     // returns Booking, throws on errors
validator(Booking).decodePromise(json);  // returns Promise<Booking>, rejects on errors
validator(Booking).decodeEither(json);   // returns Either<Array<string>, Booking>
validator(Booking).decodeAsync(json, (errors, booking) => { ... });  // returns void

JavaScript Type Signatures

In previous chapter we showed how to use the package for basic runtime input validation. However, the io-ts codecs defined in this package are also compatibile with static type systems. You can use JSDoc comments to add type signatures to your existing JavaScript code. This makes it possible for an IDE to validate the types in realtime as you are typing code in your code editor.

const { validator } = require('io-ts-validator');
const { IdentityId } = require('maas-schemas/lib/io-ts/core/components/units');
/** @typedef {import('maas-schemas/lib/io-ts/core/components/units').IdentityId} IdentityId */

/** Ignores an identity id
 *
 * @param {IdentityId} id
 * @returns {void}
 */
function ignore(id) {
  // Nothing to do
}

const raw = '916715ef-2e04-47e0-b1a5-feece4861c66';
const valid = validator(IdentityId).decodeSync(raw);

ignore(raw); // type error: string !== IdentityId
ignore(valid); // no error

TypeScript Type Signatures

If you end up using static types a lot, you may wish to use the TypeScript compiler for post processing of your JavaScript code. The TypeScript compiler can check your static type signatures at compile time and also lets you create special .ts files with embedded type signatures. For an example of embeded type signatures, see the example below.

import { validator } from 'io-ts-validator';
import { IdentityId } from 'maas-schemas/lib/io-ts/core/components/units';

function ignore(id: IdentityId): void {
  // Nothing to do
}

const raw = '916715ef-2e04-47e0-b1a5-feece4861c66';
const valid = validator(IdentityId).decodeSync(raw);

ignore(raw); // type error: string !== IdentityId
ignore(valid); // no error

Development

Automatic Conversion

Parts of the maas-schemas package are generated automatically. CI won't accept any changes to maas-schemas unless you run the converter. You can run the converter as follows.

yarn              # install dependencies
yarn convert-all  # run the converter

Documentation

Markdown and HTML documentation can be generated from JSON Schemas. To generate documentation from JSON Schemas, execute:

yarn build
yarn docs

After that, documentation will be available in Markdown format in docs/ folder and in HTML format in docs/html folder.