Strummer

https://github.com/tabcorp/strummer
Admin
Strummer is a structural-matching library for JavaScript that validates data structures against...
Tokens:4,785
Snippets:68
Trust Score:7
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Strummer

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Install the strummer package using npm.

```bash
npm install strummer
```

--------------------------------

### Example JSON Schema Output

Source: https://github.com/tabcorp/strummer/blob/master/README.md

This is an example of the JSON Schema output generated by Strummer for a given schema definition.

```json
{
  type: 'object',
  required: ['foo', 'num'],
  properties: {
    foo: {
      type: 'string'
    },
    bar: {
      type: 'string',
      description: 'Lorem Ipsum'
    },
    num: {
      type: 'number',
      maximum: 100,
      minimum: 0
    }
  }
}
```

--------------------------------

### Number Matcher with Constraints

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Example of creating a number matcher with minimum and maximum value constraints.

```javascript
new s.number({min:1, max:100})
```

--------------------------------

### Create Custom Matcher with s.createMatcher Helper

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Use the `s.createMatcher` helper function for a more concise way to define custom matchers. Implement `initialize` for setup and `match` for validation logic.

```javascript
var MyMatcher = s.createMatcher({
  initialize: function() {
    // initialize here
    // you can use "this" to store local data
  },
  match: function(path, value) {
    // validate here
    // you can also use "this"
  }
});
```

--------------------------------

### Complex Schema Definition for Performance Example

Source: https://github.com/tabcorp/strummer/blob/master/README.md

This example demonstrates a complex schema with various types including UUID, strings, numbers, arrays, enums, and regular expressions. It's used to illustrate performance considerations by showing validation statistics.

```javascript
new s.object({
  id: new s.uuid({version: 4}),
  name: 'string',
  age: new s.number({optional: true, min: 1, max: 100}),
  addresses: new s.array({of: {
    type: 'string',
    city: 'string',
    postcode: 'number'
  }}),
  nicknames: [{max: 3, of: 'string'}],
  phones: [{of: {
    type: new s.enum({values: ['MOBILE', 'HOME']}),
    number: /^[0-9]{10}$/
  }}]
})
```

--------------------------------

### Performance Statistics Example

Source: https://github.com/tabcorp/strummer/blob/master/README.md

This table shows performance statistics for Strummer, indicating the number of validations performed and the total time taken in milliseconds. This is typically generated as part of the unit test suite.

```text
┌───────────────────────┬─────────────────┐
│ Number of validations │ Total time (ms) │
├───────────────────────┼─────────────────┤
│ 10,000                │ 85              │
└───────────────────────┴─────────────────┘
```

--------------------------------

### Define a Person Schema

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Define a schema for a person object including name, age, address, and nicknames using Strummer's shorthand syntax. This example also shows how to use the match method to validate data.

```javascript
var s = require('strummer');

var person = s({
  name: 'string',
  age: 'number',
  address: {
    city: 'string',
    postcode: 'number'
  },
  nicknames: ['string']
});

console.log(person.match(bob));

// [
//   { path: 'name', value: null, message: 'should be a string' }
//   { path: 'address.postcode', value: 'NY', message: 'should be a number' }
// ]
```

--------------------------------

### Strummer Assertion Examples

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Use `s.assert` for throwing errors during validation, typically in unit tests. It checks a value against a schema and throws an `AssertionError` if validation fails, providing detailed error messages.

```javascript
s.assert(name, 'string');
// name should be a string (but was null)

s.assert(nicknames, ['string']);
// name[2] should be a string (but was 123)
// name[3] should be a string (but was 456)

s.assert(person, {
  name: 'string',
  age: new s.number({max: 200})
});
// person.age should be a number <= 200 (but was 250)
```

--------------------------------

### Optional Field Definition

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Example of defining an optional number field using the `{optional: true}` argument. This allows the field to be absent in the data being validated.

```javascript
new s.number({optional: true, min: 1})
```

--------------------------------

### Match string values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'string' or s.string() to match any string. Optional min/max length constraints are available.

```javascript
// match any string
name: 'string'
name: s.string()

// optional min and max value
name: s.string({min: 2, max: 50})
```

--------------------------------

### Match URL values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'url' or s.url() to validate URL strings.

```javascript
//match a valid url
address: 'url'
address: s.url()
```

--------------------------------

### Reusable Matcher Definitions

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Demonstrates how to define and reuse individual matchers for better organization and readability in complex schemas. Here, 'age' and 'address' matchers are defined separately and then used in the 'person' schema.

```javascript
var age = new s.number({min: 1, max: 100})

var address = new s.object({
  city: 'string',
  postcode: 'number'
});

var person = new s.object({
  name: 'string',
  age: age,
  home: address
});
```

--------------------------------

### Match any array or array of matchers

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'array' to match any array. Provide a matcher or an array of matchers to validate elements. Options for min/max elements are available.

```javascript
// match any array
nicknames: 'array'

// match an array of matchers
nicknames: ['number']
nicknames: [s.number({min: 5})]
nicknames: [s.object({text: 'string'})]

// match an array of matchers (full syntax)
nicknames: s.array('number')
nicknames: s.array(s.number({min: 5}));

// optional min and max number of elements
nicknames: s.array({min: 3, of: 'number'})
nicknames: s.array({max: 7, of: s.number({min: 5})})
nicknames: s.array({max: 7, of: s.object({name: 'string'})})
```

--------------------------------

### Match integer values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'integer' or s.integer() to match integers. Optional min/max values and a 'parse' option for string conversion are available.

```javascript
// match any integer
numberOfKids: 'integer'
numberOfKids: s.integer()

// optional min and max value
numberOfKids: s.integer({min: 0, max: 100})

// optionally parse a string into an integer e.g. "120"
numberOfKids: s.integer({parse: true, min: 0, max: 100})
```

--------------------------------

### Match number values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'number' or s.number() to match any number. Optional min/max values and a 'parse' option for string conversion are available.

```javascript
// match any number
age: 'number'
age: s.number()

// optional min and max value
age: s.number({min: 0, max: 100})

// optionally parse a string into a number e.g. "1"/"1.2"
age: s.number({parse: true})
```

--------------------------------

### Match ISO8601 dates

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'isoDate' or s.isoDate() to match dates in ISO8601 format. The 'time' option includes time components.

```javascript
updated: 'isoDate'
updated: s.isoDate({time: true})
```

--------------------------------

### Using Custom Matcher in Schema Definition

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Instantiate your custom matcher like any built-in matcher when defining a schema object.

```javascript
new s.object({
  name: 'string',
  id: new MyMatcher({max: 3})
})
```

--------------------------------

### Match hashmap values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use s.hashmap() to match key-value pairs. Specify only the value type, or define matchers for both keys and values.

```javascript
// only match the value type
map: s.hashmap('number')
map: s.hashmap(s.number({max: 10}))

// match keys and value types
map: s.hashmap({
  keys: 'string'
  values: 'number'
})

// or using more complex matchers
map: s.hashmap({
  keys: /^[a-z]{5}$/
  values: s.array(s.number({max: 10}))
})
```

--------------------------------

### Match function values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'func' or s.func() to match function types. The 'arity' option can specify the expected number of parameters.

```javascript
// match any function
cb: 'func'
cb: s.func()

// match a function with 3 parameters
cb: s.func({arity: 3})
```

--------------------------------

### Define Custom Matcher by Inheriting s.Matcher

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Inherit from `s.Matcher` and implement the `_match` function to create a custom matcher. The `_match` function should return `null` if the value matches, an error string for a single error, or an array of error objects for multiple errors.

```javascript
var s = require('strummer');

function MyMatcher(opts) {
  s.Matcher.call(this, opts);
}

util.inherits(MyMatcher, s.Matcher);

MyMatcher.prototype._match = function(path, value) {
  // if this is a leaf matcher, we only care about the current value
  return null;
  return 'should be a string starting with ABC';
  // if this matcher has children, we need to return an array of errors;
  return [];
  return [
    { path: path + '[0]', value: value[0], message: 'should be > 10' }
    { path: path + '[1]', value: value[1], message: 'should be > 20' }
  ]
};
```

--------------------------------

### Match IPv4 addresses

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use s.ip({version: 4}) to match IPv4 addresses in dot-decimal notation.

```javascript
// match any IPv4 address in dot-decimal notation, eg. 192.168.0.1
ip: s.ip({version: 4})
```

--------------------------------

### Match object structures

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'object' or s.object() to match objects. Properties can be defined with nested matchers. Extra properties are ignored.

```javascript
// match any object
person: 'object'
person: s.object()

// match an object with given properties
person: s.object({
  name: 'string'
  age: 'number'
})

// can be simplified to
person: {
  name: 'string'
  age: 'number'
}

// match a nested object
person: {
  name: 'string'
  address: {
    city: 'string'
    postcode: 'number'
  }
}
```

--------------------------------

### Match duration strings

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'duration' or s.duration() to match time spans like '10s', '5m', '24h'. Optional min/max values can be specified.

```javascript
timespan: 'duration'
timespan: s.duration()
timespan: s.duration({min: '10s', max: '5m'})
```

--------------------------------

### Match UUID values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'uuid' or s.uuid() to match universally unique identifiers. Specify the version (e.g., 4) for stricter matching.

```javascript
// match any valid UUID
id: 'uuid'
id: s.uuid()

// only match a specific version
id: s.uuid({version: 4})
```

--------------------------------

### Match regex patterns

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use a regex literal or s.regex() to match strings against a regular expression.

```javascript
// match a given regex
name: /^[a-z]+$/i
name: s.regex(/^[a-z]+$/i)
```

--------------------------------

### Match one of several options

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use s.oneOf() to match a value against a list of alternative matchers, including strings, enums, booleans, or objects.

```javascript
param: s.oneOf([
  'string',
  s.enum({ values: [1, 2, 3] }),
  'boolean',
  s.object({
    name: 'string'
  })
]);
```

--------------------------------

### Match email addresses

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'email' or s.email() to validate email addresses. Optionally specify a domain for targeted matching.

```javascript
// match any valid email
id: 'email'
id: s.email()

// only match a specific domain
id: s.email({domain: 'example.org'})
```

--------------------------------

### Define Custom Constraint Function

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Apply custom constraints by passing a function to the schema's options. This function receives the path and value, and should return an array of errors if constraints are violated. Currently, this is primarily supported for `objectWithOnly`.

```javascript
var constraintFunc = function (path, value) {
  if (value.street_number && !value.post_code) {
    return [{
      path: path,
      value: value,
      error: 'post_code is requried with a street_number'
    }]
  }

  return []
}

var schema = new objectWithOnly({
  email_address: new string(),
  street_number: new number({optional: true}),
  post_code: new number({optional: true}),
}, {
  constraints: constraintFunc
});

var value = {
  email_address: 'test@strummer.com',
  street_number: 12,
}

const errors = schema.match(value)
// will error with post_code is requried with a street_number
```

--------------------------------

### Match enum values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use s.enum() to match values from a predefined list. The 'name' and 'verbose' options control error messages, and 'type' can specify the schema type.

```javascript
// list of possible values
state: s.enum({values: ['NSW', 'VIC']})

// displays "should be a valid state"
state: s.enum({values: ['NSW', 'VIC'], name:'state'})

// displays "should be a valid state (NSW,VIC)"
state: s.enum({values: ['NSW', 'VIC'], name:'state', verbose: true})

// you can pass in the enum type, which will be used in the jsonschema output
state: s.enum({type: 'string', values: ['NSW', 'VIC']})
```

--------------------------------

### Match boolean values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use 'boolean' or s.boolean() to match boolean values. The 'parse' option allows string conversion of 'true' or 'false'.

```javascript
// match a boolean
enabled: 'boolean'
enabled: s.boolean()

// optionally parse a string into a boolean e.g. "true"/"false"
enabled: s.boolean({parse: true})
```

--------------------------------

### Match specific primitive values

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use s.value() for strict equality checks against primitive values like booleans or numbers.

```javascript
// test for strict equality on primitives
promotionSelected: s.value(false)
```

--------------------------------

### Generate JSON Schema from Strummer Definition

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Strummer can generate a basic JSON Schema representation of your defined schemas. Implement the `toJSONSchema` option in `createMatcher` for custom matchers to include them in the generated schema.

```javascript
var schema = s({
  foo: 'string',
  bar: s.string({ optional: true, description: 'Lorem Ipsum' }),
  num: s.number({ max: 100, min: 0 })
});

console.log(schema.toJSONSchema());
```

--------------------------------

### Strummer Schema Definition (Verbose)

Source: https://github.com/tabcorp/strummer/blob/master/README.md

An alternative, more verbose way to define the person schema using Strummer's matcher classes directly. This demonstrates the underlying structure of the shorthand syntax.

```javascript
var person = new s.object({
  name: new s.string(),
  age: new s.number(),
  address: new s.object({
    city: new s.string(),
    postcode: new s.number()
  }),
  nicknames: new s.array({of: new s.string()})
});
```

--------------------------------

### Match exact object structures

Source: https://github.com/tabcorp/strummer/blob/master/MATCHERS.md

Use s.objectWithOnly() to match an object with specific properties, disallowing extra properties. Nested objects can also be matched exactly.

```javascript
// match an object with given properties
person: s.objectWithOnly({
  name: 'string'
  age: 'number'
})

// match a nested object
person: s.objectWithOnly({
  name: 'string'
  address: s.objectWithOnly({
    city: 'string'
    postcode: 'number'
  })
})
```

--------------------------------

### Complex Person Schema Definition

Source: https://github.com/tabcorp/strummer/blob/master/README.md

Define a complex schema for a person including nested objects, arrays with constraints, enums, and UUIDs. This showcases Strummer's ability to handle intricate data structures.

```javascript
var person = new s.object({
  id: new s.uuid({version: 4}),
  name: 'string',
  age: new s.number({min: 1, max: 100}),
  address: {
    city: 'string',
    postcode: 'number'
  },
  nicknames: [{max: 3, of: 'string'}],
  phones: [{of: {
    type: new s.enum({values: ['MOBILE', 'HOME']}),
    number: 'number'
  }}]
});
```
Tokens:
Raw