@break-point/specjs

SpecJS

Design by contract javascript library

THIS LIBRARY STILL IN EARLY DEVELOPMENT, IT'S NOT STABLE, AND USAGE IN PRODUCTION IS NOT RECOMMENDED YET.

SpecJS is a tiny (≈0.7KB) to implement design by contract in Javascript and Typescript projects. To start learning how to use the library, take a look at the usage section. Afterward you'll find more information in the examples and reading the tests.

Try it now.

Installation

From NPM

$ npm install @alfonsofilho/specjs --save

Or yarn:

$ yarn add @alfonsofilho/specjs

Then import/require the module.

const SpecJS = require('@alfonsofilho/specjs');
// or
import { bindSpec } from '@alfonsofilho/specjs';

From CDN

Place the snippet into your html:

<script src="https://unpkg.com/@alfonsofilho/specjs@0.0.1/dist/specjs.umd.js"></script>

This file is a bundle in the UMD format. In the browser's environments, the module name is in available in window.SpecJS.

See more in examples.

Usage

Most basic usage:

import { Sign, conditions, isRequired, check } from '@alfonsofilho/specjs';

// 1. Write the Contract
const toUpperContract = (text: string) => ({
  pre: conditions(
    isRequired(text),
    check(() => text.length > 0)
  ),
  post: conditions(
    check((result: string) => result === text.toUpperCase())
  )
})

// 2. Write the function or class
function toUpper(text: string): string {
  return text.toUppercase(text)
}

// 3. Bind the implementation and the contract
const toUpperSigned = Sign(toUpper, toUpperContract)

// 4. Use the signed function with the runtime
//    guarantees provided by the contract
toUpperSigned('test') === 'TEST' // OK
toUpperSigner('') === 'TEST' // Precondition fails

Built with

• Typescript
• Jest
• Microbundle

Other nice JavaScript libraries:

There are many interesting projects out there implementing design by contract. Search more in NPM.

Learn more about design by contract

• https://en.wikipedia.org/wiki/Design_by_contract
• https://www.sciencedirect.com/topics/computer-science/design-by-contract
• https://www.eiffel.org/doc/solutions/Design_by_Contract_and_Assertions
• https://www.eiffel.com/values/design-by-contract/
• https://www.leadingagile.com/2018/05/design-by-contract-part-one/
• https://www.microsoft.com/en-us/research/project/spec/

Contributing

• Improving or correcting the documentation.
• Translating.
• Finding bugs
• Sharing this project.
• PRs are very welcome.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG file for details.