ValidatedMethod

Provides runtime type checking for JavaScript function parameters similar to TypeScript, but with no compiling or dependencies.

Features

• Zero dependencies
• TypeScript-like parameter validation in pure JavaScript
• Named, single, and positional parameter support
• Coercion options for numbers and booleans
• Regular Expression validation for strings
• Custom type support
• Extra parameter warnings
• Optional return type validation
• Easy to integrate with intuitive syntax
• Supports async / Promsie chaining
• Full test suite included

Installation

Install via npm.

npm i validated-method

Or import from CDN.

import{ValidatedMethod}from'https://unpkg.com/validated-method/validated-method.js';

Or copy validated-method.js into your project.

Usage

import{ValidatedMethod}from'validated-method';classUserService{createUser=newValidatedMethod({username: 'string',age: 'number',active: 'boolean',roles: 'array',settings: 'object',email: /^[^@]+@[^@]+\.[^@]+$/,birthday: ['string','optional']title: 'string'},asyncopts=>{// Parameters are validated, safe to usereturnawaitdb.users.create(opts);});}constmyService=newUserService();myService.createUser({username: 'besworks',age: 40,active: true,roles: ['admin','wizard'],settings: {darkmode: 'auto'},email: 'example@domain.tld',// birthday: is optional so undefined is ok// Throw TypeError because title: is undefined});

Type Validation

Basic Types

• 'string' - String values
• 'boolean' - Truthy/Falsey values (coerced using Boolean())
• 'object' - Object literals
• 'array' - Arrays of any length including 0
• 'function' - Executable functions
• 'null' - Empty values

Number Types

• 'int' - Integers with truncating coercion (uses parseInt())
• 'roundint' - Integers with rounding coercion (uses Math.round())
• 'strictint' - Integers without coercion
• 'number' - Alias of 'float'
• 'float' - Floating point numbers with coercion (uses parseFloat())
• 'strictfloat' - Floating point numbers without coercion

Special Types

• 'any' - Any value including null, except undefined
• 'undefined' - Alias of 'optional'
• 'optional' - Value can be undefined
• 'strictboolean' - Booleans only without coercion
• /^test$/ig - Regular Expression literal (without quotes, uses toString())
• ClassName - Class comparison (using instanceof)
• (a) => a === b - any declared or incline function can be used as a validator

Import Alias

The _$ helper is provided for convenience but can be renamed on import if it conflicts with other libraries:

import{_$asVM}from'validated-method';constgetData=VM('string',performLookupByName);

Custom Types

classWidget{node=document.getElementById('widget')??document.createElement('custom-widget');}constconfigureWidget=_$({widget: Widget,className: 'string'},opts=>{opts.widget.node.classList.add(opts.className);// safe to call classList because we know// opts.widget.node is an HTMLElement// and opts.className is a string});configureWidget(newWidget(),'green');

Extra Parameter Warnings

By default, ValidatedMethod warns about unexpected parameters:

constaddRecord=_$({name: 'string',age: 'number'},insertData);addRecord({name: 'test',age: 40,extra: true// Warning: "Unexpected parameter: extra"});

Quiet Mode

You can globally supress warnings with the static quiet flag.

ValidatedMethod.quiet=true;constgetData=_$({bleep: 'boolean',bloop: 'array'},opts=>{return{e: opts.bleep,o: opts.bloop}});constref={bleep: true,bloop: [],derp: { ...bigObj},zzz: 'more'};getData(ref);// no warnings, best for production

Parameter Styles

Named Parameters

constmethod=_$({name: 'string',age: 'number'},opts=>`${opts.name} is ${opts.age}`);method({name: 'Test',age: 42});

Single Parameter

// Using type identifierconst$=_$('string',query=>document.querySelector(query));$('.my-element');// Using Custom classconstprocess=_$(CustomType,instance=>instance.process());

Positional Parameters

constadd=_$(['number','number'],(a,b)=>a+b);add(40,2);// Returns 42constdelayed=_$(['int','function'],(ms,callback)=>setTimeout(callback,ms));delayed(1000,()=>console.log('Done!'));

Zero Parameter Functions

For functions that take no parameters, you can use any of these equivalent forms:

// These all create a parameterless function that returns a numberconstfn1=_$(undefined,()=>42,'number');constfn2=_$(null,()=>42,'number');constfn3=_$('void',()=>42,'number');constfn4=_$([],()=>42,'number');constresult=fn1();// Returns 42fn1(42);// Throws: Expected 0 arguments, got 1

Custom Validators

You can use functions as input type validators. They must be synchronous and return a truthy/falsey value.

constisEven=n=>n%2===0;constgetHalf=_$(isEven,num=>num/2);getHalf(42);// Accepted inputgetHalf(43);// TypeError// declared inlineconstref=1;constgetExact=_$(a=>a===ref,num=>num);

Error Handling

Throws a TypeError for validation failures:

• Missing required parameters
• Type mismatches
• Coercion failures
• Invalid custom type instances

Return Type Validation

You can optionally specify an expected return type as the third parameter.

Supported Return Types

• All input type identifiers ('string', 'number', 'boolean', 'null', etc)
• Custom classes (validates instanceof)
• Regular expressions (tests string conversion)
• Array of types for multiple options
• Special types:
  • 'void' or undefined - Must return undefined
  • 'any' - Any value except undefined
  • 'optional' - Included for completeness, this is the same as not specifying a return type. Return type is not checked.
  • a => a === b - Use any declared or inline function to validate output

Return Type Examples

// Ensure function returns a stringconstupperCase=_$('string',str=>str.toUpperCase(),'string');// Validate class instances// including custom and built in typesconstgetUser=_$('number',id=>db.findUser(id),User);constgetNodes=_$([Node,'string'],(el,q)=>el.querySelectorAll(q),NodeList);// Allow multiple return typesconstgetValue=_$('string',key=>cache.get(key),['string','null']);// Explicit void return, must return undefinedconstlogMessage=_$('string',msg=>{console.log(msg);},'void');// Any non-undefined return, null allowedconstprocess=_$('object',data=>processData(data),'any');// Regular Expression test string outputconstcheckValue=_$('string',str=>procesValue(str),/^testing$/i);// custom validator functionconstoffset=10;constgetPositive=_$('number',num=>num-offset,n=>n>0);getPositive(5);// returns -5, would fail validation// check by referenceconstcomplexTask=_$(null,doSomething,checkResults);