function-schema v0.1.0

Install

npm install function-schema

Usage

import { signature } from 'function-schema';

const myFunction = signature(...ParamTypeChecks)(ReturnValueCheck)(functionDefinition);

Examples:

Define your function signature

import { signature, Void } from 'function-schema';

// myFunction(name: string): void
const myFunction = signature(String)(Void)(
  (name) => console.log(`Hello, ${name}`),
)

Invoke your function:

myFunction('Stan'); // "Hello, Stan"

myFunction(300); // TypeCheckError: Parameter 0 must be an instance of string, received number instead

Return value:

import { signature } from 'function-schema';

// myFunction(name: string): string
const myFunction = signature(String)(String)(
  (name) => `Hello, ${name}`,
)

Optional parameters

import { signature, Optional, Int } from 'function-schema';

// myFunction(name: string, age: Optional<int>): string
const myFunction = signature(String, Optional(Int))(String)(
  (name, age) => `I'm ${name}, and I'm ${age !== undefined ? age : 'infinite'} years old`,
);

myFunction('John', 17); // "I'm John, and I'm 17 years old"
myFunction('Duncan'); // "I'm John, and I'm infinite years old"
myFunction('Didact', null); // "I'm Didact, and I'm infinite years old"
myFunction('Zima', undefined); // "I'm Zima, and I'm infinite years old"

myFunction('Josh', 'Foo'); // TypeCheckError: Parameter 1 must be an instance of Optional<int>, received string instead

Instance Of

import { signature, InstanceOf } from 'function-schema';

class MyClass {
  constructor(name){
    this.name = name;
  }
};

// myFunction(param: MyClass): void
const myFunction = signature(InstanceOf(MyClass))()(
  (param) => console.log(param),
);

// This would have the exact same effect since InstanceOf is the default type check.
const myFunction = signature(MyClass)()(
  (param) => console.log(param),
);

myFunction(new MyClass('John')); // MyClass { name: 'John' }

myFunction(); // TypeCheckError: Parameter 0 must be an instance of MyClass, received undefined instead
myFunction({ name: 'John' }); // TypeCheckError: Parameter 0 must be an instance of MyClass, received object instead

Any

import { signature, Any } from 'function-schema';

// myFunction(name: any): void
const myFunction = signature(Any)()(
  (something) => console.log(something),
)

// myFunction Accepts anything!

myFunction(); // undefined
myFunction(null); // null
myFunction(500); // 500
myFunction('Steve'); // 'Steve'
myFunction({ x: 0, y: 0 }); // { x: 0, y: 0 }

One Of

import { signature, OneOf } from 'function-schema';

const myFunction = signature(OneOf(String, Number))()(
  (value) => console.log(value);
);

myFunction('A string!'); // 'A string!'
myFunction(600); // 600

myFunction(); // TypeCheckError: Parameter 0 must be an instance of OneOf<string, number>, received undefined instead
myFunction(null);  // TypeCheckError: Parameter 0 must be an instance of OneOf<string, number>, received object instead
myFunction(undefined);  // TypeCheckError: Parameter 0 must be an instance of OneOf<string, number>, received undefined instead
myFunction({});  // TypeCheckError: Parameter 0 must be an instance of OneOf<string, number>, received object instead
myFunction(() => 'Boom!');  // TypeCheckError: Parameter 0 must be an instance of OneOf<string, number>, received function instead

Struct

import { signature, Struct } from 'function-schema';

// Define your structure:
const MyType = Struct({
  name: String,
  age: Int,
  favoriteGame: Optional(String),
});

// Define your function
const myFunction = signature(MyType)(String)(
  ({ name, age, favoriteGame}) 
    => `This is ${name}, I'm ${age} years old and ${favoriteGame ? `my favorite game is ${favoriteGame}` : 'have no favorite game'}`;
);

myFunction({
  name: 'John',
  age: 17,
  favoriteGame: 'Halo'
}); // "This is John, I'm 17 years old and my favorite game is Halo"

myFunction({
  name: 'Albert',
  age: 98,
}); // "This is Albert, I'm 94 years old and I have no favorite game"

myFunction({ }); 
// TypeCheckError: Parameter 0 must be an instance of {
// name: string,
// age: int,
// favoriteGame: Optional<String>
// }, received object with these errors: 
//  - name: Parameter 0 must be an instance of string, received undefined instead,
//  - age: Parameter 0 must be an instance of int, received undefined instead
//  instead

Promise Of

import { signature, PromiseOf } from 'function-schema';

const myPromiseProducingFunction = signature()(PromiseOf(String))(
  () => new Promise((accept) => accept('Some Text'))
);

// Or

const myAsyncFunction = signature()(PromiseOf(String))(
  async () => {
    const result = await somePromiseFunction();
    return result;
  }
);

Any

import { signature, Any } from 'function-schema';

// myFunction(name: any): void
const myFunction = signature(Any)()(
  (something) => console.log(something),
)

// myFunction Accepts anything!

myFunction(); // undefined
myFunction(null); // null
myFunction(500); // 500
myFunction('Steve'); // 'Steve'
myFunction({ x: 0, y: 0 }); // { x: 0, y: 0 }

Variadic

import { signature, Variadic } from 'function-schema';

const myFunction = signature(Number, Variadic(String))()(
  (numericValue, ...variadicValues) => console.log(numericValue, variadicValues);
);

myFunction(600); // 600, []
myFunction(600, 'String1'); // 600, ['String1']
myFunction(600, 'String1', 'String2'); // 600, ['String1', 'String2']

myFunction(600, null); // TypeCheckError: Parameter 1 must be an instance of ...string[], received null@1 instead
myFunction(600, 'String1', undefined); // TypeCheckError: Parameter 1 must be an instance of ...string[], received undefined@2 instead
myFunction(600, 'String1', 100, 'String2', 300); // TypeCheckError: Parameter 1 must be an instance of ...string[], received number@2, number@4 instead

Warning For the sake of clarity, only use Variadic as last parameter, it can technically be used in the middle, but that'd be confusing and, at certain circumstances, cause unpredictable behaviors.

ArrayOf

import { signature, ArrayOf } from 'function-schema';

const myFunction = signature(ArrayOf(String))()(
  (arrayOfStrings) => console.log(arrayOfStrings);
);

myFunction([]); // []
myFunction(['String1']); // ['String1']
myFunction(['String1', 'String2']); // ['String1', 'String2']

myFunction(null); // TypeCheckError: Parameter 0 must be an instance of string[], received null instead
myFunction(['String1', undefined]); // TypeCheckError: Parameter 0 must be an instance of string[], received [..., undefined@1] instead
myFunction(['String1', 100, 'String2', 300]); // TypeCheckError: Parameter 0 must be an instance of string[], received [..., number@1, ...] instead

Note: Since arrays could potentially be big, this check will stop at the first invalid entry, all subsequent elements will be ignored.

Tuple

import { signature, Tuple } from 'function-schema';

const myFunction = signature(Tuple(String, Number))()(
  (tuple) => console.log(tuple);
);

myFunction(['String1', 100]); // ['String1', 'String2']
myFunction(['String1', 100, 'Ignored Value']); // ['String1', 100, 'Ignored Value']

myFunction(null); // TypeCheckError: Parameter 0 must be an instance of (string, number), received null instead
myFunction(['String1', undefined]); // TypeCheckError: Parameter 0 must be an instance of (string, number), received (string, undefined) instead
myFunction(['String1', 'String2', 300]); // TypeCheckError: Parameter 0 must be an instance of (string, number), received (string, string) instead

Use signatures as function factories

import { signature } from 'function-schema';

const RequestHandler = signature(MyRequestClass)(MyResponseClass);

const listUsers = RequestHandler((request) => new MyResponseClass());
const createUser = RequestHandler((request) => new MyResponseClass());

Define custom type checks

// A simple type check
const Email = new TypeCheck('email', (entry) => is.email(entry.value));

// A type check with parameters
const NumberRange = (lowerRange, upperRange) => new TypeCheck(`number(from ${lowerRange} to ${upperRange})`, ({value}) => {
  return is.number(value) && value >= lowerRange && value <= upperRange;
});

Generics (sort of)

const MapDelegate = (T, R) => signature(T)(R);

const numbersToString = MapDelegate(Number, String)((n) => n.toString());

[1, 2, 3, 4].map(numbersToString); // ['1', '2', '3', '4'];

[1, '!', 3, 4].map(numbersToString); // TypeCheckError: Parameter 0 must be an instance of number, received string instead.

All type checks so far

Thanks to:

• @arasatasaygin - For the is.js library from which I'm actively stealing checks for this library.

TODO

Get rid of is.js dependency.

Future Checks:

• Truthy
• Falsy

String Checks

• Matches
• Email
• Url
• NumericString
• IntString
• BooleanString: Case insensitive version of OneOf('true', 'false')

Collection Checks

• Variadic
• ArrayOf
• Tuple: Understanding tuple as [TypeCheck1, TypeCheck2, ...]

Type Constraints?

(This one looks tricky, might not be a good idea)

Constrained(TypeCheck, Constraint1, Constraint2)
// Or...
TypeCheck.where(Constraint1, Constraint2);

• Min
• Max
• Range
• MinLength
• MaxLength
• RangeLength
• (value) => boolean