Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

superstruct

Package Overview
Dependencies
Maintainers
1
Versions
90
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

superstruct - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

docs/guide.md
docs/reference.md
examples/optional-values.js
examples/returning-errors.js

9

examples/basic-validation.js

@@ -1,7 +0,6 @@

/* eslint-disable no-console */
import struct from '..'
import { struct } from 'superstruct'
// Define a struct to validate with.
const validate = struct({
const User = struct({
id: 'number',

@@ -24,6 +23,6 @@ name: 'string',

// Validate the data by calling `validate`. In this case, the data is valid, so
// Validate the data by calling `assert`. In this case, the data is valid, so
// it will not throw.
try {
validate(data)
User.assert(data)
console.log('Valid!')

@@ -30,0 +29,0 @@ } catch (e) {

11

examples/composing-structs.js

@@ -1,7 +0,6 @@

/* eslint-disable no-console */
import struct from '..'
import { struct } from 'superstruct'
// Define a `user` struct.
const isUser = struct({
const User = struct({
id: 'number',

@@ -13,3 +12,3 @@ name: 'string',

// `author` property.
const isArticle = struct({
const Article = struct({
id: 'number',

@@ -19,3 +18,3 @@ title: 'string',

published_at: 'date?',
author: isUser,
author: User,
})

@@ -37,3 +36,3 @@

try {
isArticle(data)
Article.assert(data)
console.log('Valid!')

@@ -40,0 +39,0 @@ } catch (e) {

32

examples/custom-errors.js

@@ -1,7 +0,6 @@

/* eslint-disable no-console */
import struct from '..'
import { struct } from 'superstruct'
// Define a struct to validate with.
const validate = struct({
const User = struct({
id: 'number',

@@ -19,7 +18,7 @@ name: 'string',

// Validate the data by calling `validate`. In this case the `name` property is
// Validate the data by calling `assert`. In this case the `name` property is
// invalid, so an error will be thrown that you can catch and customize to your
// needs.
try {
validate(data)
User.assert(data)
console.log('Valid!')

@@ -29,17 +28,20 @@ } catch (e) {

case 'property_invalid': {
const err = new Error(`user_${e.key}_invalid`)
err.attribute = e.key
err.value = e.value
throw err
const error = new Error(`user_${e.key}_invalid`)
error.attribute = e.key
error.value = e.value
throw error
}
case 'property_required': {
const err = new Error(`user_${e.key}_required`)
err.attribute = e.key
throw err
const error = new Error(`user_${e.key}_required`)
error.attribute = e.key
throw error
}
case 'property_unknown': {
const err = new Error(`user_attribute_unknown`)
err.attribute = e.key
throw err
const error = new Error(`user_attribute_unknown`)
error.attribute = e.key
throw error
}
default: {
throw e
}
}

@@ -46,0 +48,0 @@ }

11

examples/custom-types.js

@@ -1,4 +0,3 @@

/* eslint-disable no-console */
import { superstruct } from '..'
import { superstruct } from 'superstruct'
import isEmail from 'is-email'

@@ -17,4 +16,4 @@ import isUuid from 'is-uuid'

// Define a struct which returns a `validate` function.
const validate = struct({
// Define a struct to validate with.
const User = struct({
id: 'uuid',

@@ -34,6 +33,6 @@ name: 'string',

// Validate the data by calling `validate`. In this case, the data is valid, so
// Validate the data by calling `assert`. In this case, the data is valid, so
// it will not throw.
try {
validate(data)
User.assert(data)
console.log('Valid!')

@@ -40,0 +39,0 @@ } catch (e) {

9

examples/default-values.js

@@ -1,4 +0,3 @@

/* eslint-disable no-console */
import struct from '..'
import { struct } from 'superstruct'

@@ -9,3 +8,3 @@ // Define an auto-incrementing unique id.

// Define a struct to validate with.
const validate = struct({
const User = struct({
id: 'number',

@@ -31,3 +30,3 @@ name: 'string',

// Validate the data by calling `validate`, and storing the return value in the
// Validate the data by calling `assert`, and storing the return value in the
// `user` variable. Any property that wasn't defined will be set to its default.

@@ -37,3 +36,3 @@ let user

try {
user = validate(data)
user = User.assert(data)
console.log('Valid!', user)

@@ -40,0 +39,0 @@ } catch (e) {

9

examples/throwing-errors.js

@@ -1,7 +0,6 @@

/* eslint-disable no-console */
import struct from '..'
import { struct } from 'superstruct'
// Define a struct to validate with.
const validate = struct({
const User = struct({
id: 'number',

@@ -19,6 +18,6 @@ name: 'string',

// Validate the data by calling `validate`. In this case the `name` property is
// Validate the data by calling `assert`. In this case the `name` property is
// invalid, so a `property_invalid` error will be thrown.
try {
validate(data)
User.assert(data)
} catch (e) {

@@ -25,0 +24,0 @@ throw e

6

lib/superstruct.js

@@ -9,5 +9,5 @@ 'use strict';

var _cloneDeep = require('lodash/cloneDeep');
var _lodash = require('lodash.clonedeep');
var _cloneDeep2 = _interopRequireDefault(_cloneDeep);
var _lodash2 = _interopRequireDefault(_lodash);

@@ -79,3 +79,3 @@ var _componentType = require('component-type');

const { defaults } = this;
return typeof defaults === 'function' ? defaults() : (0, _cloneDeep2.default)(defaults);
return typeof defaults === 'function' ? defaults() : (0, _lodash2.default)(defaults);
}

@@ -82,0 +82,0 @@

5

package.json
{
"name": "superstruct",
"description": "A simple, expressive way to validate data in Javascript.",
"version": "0.1.0",
"version": "0.1.1",
"license": "MIT",

@@ -23,3 +23,3 @@ "repository": "git://github.com/ianstormtaylor/superstruct.git",

"component-type": "^1.2.1",
"lodash": "^4.17.4"
"lodash.clonedeep": "^4.5.0"
},

@@ -42,2 +42,3 @@ "devDependencies": {

"is-uuid": "^1.0.2",
"lodash.pick": "^4.4.0",
"mocha": "^3.2.0",

@@ -44,0 +45,0 @@ "np": "^2.13.1",

70

Readme.md

@@ -33,5 +33,5 @@

Superstruct makes it easy to define interfaces and then validate Javascript data against them. Its type annotation API was inspired by [Typescript](https://www.typescriptlang.org/docs/handbook/basic-types.html), [Flow](https://flow.org/en/docs/types/), [Go](https://gobyexample.com/structs), and [GraphQL](http://graphql.org/learn/schema/), which gives it a familiar, easy to understand API.
Superstruct makes it easy to define interfaces and then validate Javascript data against them. Its type annotation API was inspired by [Typescript](https://www.typescriptlang.org/docs/handbook/basic-types.html), [Flow](https://flow.org/en/docs/types/), [Go](https://gobyexample.com/structs), and [GraphQL](http://graphql.org/learn/schema/), giving it a familiar and easy to understand API.
But Superstruct is designed for runtime data validations, so it throws detailed runtime errors for you or your end users. This is especially useful in situations like accepting arbitrary input in a REST or GraphQL API. But it can even be used to validate internal data structures in non-typed code bases.
But Superstruct is designed for validating data at runtime, so it throws (or returns) detailed runtime errors for you or your end users. This is especially useful in situations like accepting arbitrary input in a REST or GraphQL API. But it can even be used to validate internal data structures at runtime when needed.

@@ -46,5 +46,5 @@

```js
import struct from 'superstruct'
import { struct } from 'superstruct'
const validate = struct({
const Article = struct({
id: 'number',

@@ -62,3 +62,2 @@ title: 'string',

title: 'Hello World',
is_published: true,
tags: ['news', 'features'],

@@ -70,14 +69,12 @@ author: {

validate(data)
// Throws if the data is invalid.
// Returns the data (with defaults) if valid.
Article.assert(data)
// The `assert()` method throws when the data is invalid, and returns the data otherwise.
// If you'd rather not throw errors, you can use `validate()` or `test()` instead.
```
The schema definition syntax was inspired by [Typescript](https://www.typescriptlang.org/docs/handbook/basic-types.html), [Flow](https://flow.org/en/docs/types/) and [GraphQL](http://graphql.org/learn/schema/), and ships with types for all of the native Javascript types out of the box.
It recognizes all the native Javascript types out of the box. But you can also define your own custom data types—specific to your application's requirements—by using the `superstruct` export:
But you can also define your own custom data types—specific to your application's requirements—by using the exported `superstruct` function. For example:
```js
import { superstruct } from 'superstruct'
import isUuid from 'is-uuid'

@@ -88,8 +85,8 @@ import isEmail from 'is-email'

types: {
uuid: v => isUuid.v4(v),
email: v => isEmail(v) && v.length < 256,
uuid: value => isUuid.v4(value),
email: value => isEmail(value) && value.length < 256,
}
})
const validate = struct({
const User = struct({
id: 'uuid',

@@ -105,8 +102,8 @@ email: 'email',

validate(data)
// Throws if the data is invalid.
// Returns the data (with defaults) if valid.
User.assert(data)
```
Superstruct supports more complex use cases too like defining list or scalar structs, applying default values, composing structs inside each other, returning errors instead of throwing them, etc. For more information read the full [Documentation](#documentation).
<br/>

@@ -118,13 +115,13 @@

- **They don't throw errors.** Many validators simply return `true/false` or return string error messages. This was helpful in the days of callbacks, when using `throw` was discouraged, but in modern Javascript using `throw` leads to much simpler and terser code.
- **They can't throw errors.** Many validators simply return `true/false` or string errors. Although helpful in the days of callbacks, not using `throw` in modern Javascript makes code much more complex.
- **They don't expose useful error information.** For the validators that do `throw`, they often throw over-simplified, message-only errors without any extra details about the reason the error occurred. This makes it very difficult to customize the errors to make them helpful for end users.
- **They don't expose detailed errors.** For those that do `throw`, they often throw string-only errors without any details as to why, making it difficult to customize the errors to be helpful for end-users.
- **They aren't designed around custom types.** Many validators ship with built-in types like emails, URLs, UUIDs, etc. with no easy way to know how they're implemented. And when defining your own custom types—which any reasonably sized codebase needs to do—the APIs are needlessly complex and hard to re-use.
- **They make custom types hard.** Many validators ship with built-in types like emails, URLs, UUIDs, etc. with no way to know what they check for, and complicated APIs for defining new types.
- **They don't encourage single sources of truth.** Many existing APIs encourage re-defining custom data type requirements like maximum lengths, custom types, error messages, etc. over and over, with the source of truth being spread out across many files, which makes consistentcy difficult to maintain.
- **They don't encourage single sources of truth.** Many existing APIs encourage re-defining custom data types over and over, with the source of truth being spread out across your entire code base.
- **They don't compile schemas for performance.** Some validators allow you to define schemas as plain Javascript objects, which seems nice at first. But it also means that they delegate the complex parsing of the schema logic to validation time, instead of doing the work up front for performance.
- **They don't pre-compile schemas.** Many validators define schemas as plain Javascript objects, which means they delegate the parsing of the schema logic to validation time, making them much slower.
- **They are tightly coupled to other concerns.** Many validators are implemented as plugins for Express or other HTTP frameworks, which is completely unnecessary and confusing to reason about. And when you need to validate data elsewhere in your code base you end up with fragmentation.
- **They're tightly coupled to other concerns.** Many validators are tightly coupled to Express or other frameworks, which results in one-off, confusing code that isn't reusable across your code base.

@@ -146,9 +143,9 @@ Of course, not every validation library suffers from all of these issues, but most of them exhibit at least one. If you've run into this problem before, you might like Superstruct.

5. **Terse schemas.** The schemas in Superstruct are designed to be extremely terse. This makes them very easy to read and write, encouraging you to have full data validation coverage.
5. **Terse schemas.** The schemas in Superstruct are designed to be extremely terse and expressive. This makes them very easy to read and write, encouraging you to have full data validation coverage.
7. **Compiled validators.** Superstruct does the work of compiling its schemas up front, so that it doesn't have to spend lots of time performing expensive tasks for every call to the validation functions in your hot code paths.
7. **Compiled validators.** Superstruct does the work of compiling its schemas up front, so that it doesn't spend time performing expensive tasks for every call to the validation functions in your hot code paths.
6. **Useful errors.** The errors that Superstruct throws contain all the information you need to convert them into your own application-specific errors easy, which means more helpful errors for your end users!
3. **Familiar API.** The Superstruct API was heavily inspired by [Typescript](https://www.typescriptlang.org/docs/handbook/basic-types.html), [Flow](https://flow.org/en/docs/types/) and [GraphQL](http://graphql.org/learn/schema/). If you're familiar with any of those, then its schema definition API will feel very natural to use, so you can get started quickly.
3. **Familiar API.** The Superstruct API was heavily inspired by [Typescript](https://www.typescriptlang.org/docs/handbook/basic-types.html), [Flow](https://flow.org/en/docs/types/), [Go](https://gobyexample.com/structs), and [GraphQL](http://graphql.org/learn/schema/). If you're familiar with any of those, then its schema definition API will feel very natural to use, so you can get started quickly.

@@ -160,3 +157,3 @@

Superstruct's API is very flexible, allowing it to be used for a variety of use cases on your servers and in the browser. Here are a few examples to common patterns...
Superstruct's API is very flexible, allowing it to be used for a variety of use cases on your servers and in the browser. Here are a few examples of common patterns...

@@ -166,4 +163,6 @@ - [Basic Validation](./examples/basic-validation.js)

- [Default Values](./examples/default-values.js)
- [Optional Values](./examples/optional-values.js)
- [Composing Structs](./examples/composing-structs.js)
- [Throwing Errors](./examples/throwing-errors.js)
- [Returning Errors](./examples/returning-errors.js)
- [Custom Errors](./examples/custom-errors.js)

@@ -176,6 +175,15 @@

Read the **Getting Started** guide to familiarize yourself with how Superstruct works. After that, check out the full API reference...
Read the getting started guide to familiarize yourself with how Superstruct works. After that, check out the full API reference for more detailed information about structs, types and errors...
- [Getting Started](./docs/getting-started.md)
- [API Reference](./docs/api-reference.md)
- [**Guide**](./docs/guide.md)
- [Installing Superstruct](./docs/guide.md#installing-superstruct)
- [Creating Structs](./docs/guide.md#creating-structs)
- [Defining Custom Data Types](./docs/guide.md#defining-custom-data-types)
- [Setting Default Values](./docs/guide.md#setting-default-values)
- [Throwing Customized Errors](./docs/guide.md#throwing-customized-errors)
- [**Reference**](./docs/reference.md)
- [API](./docs/reference.md#api)
- [Structs](./docs/reference.md#structs)
- [Types](./docs/reference.md#types)
- [Errors](./docs/reference.md#errors)

@@ -182,0 +190,0 @@

2

src/superstruct.js
import cloneDeep from 'lodash/cloneDeep'
import cloneDeep from 'lodash.clonedeep'
import typeOf from 'component-type'

@@ -4,0 +4,0 @@ 

docs/api-reference.md
docs/getting-started.md
docs/Introduction.md
docs/Readme.md
.babelrc

Sorry, the diff of this file is not supported yet

dist/superstruct.js

Sorry, the diff of this file is too big to display

dist/superstruct.min.js

Sorry, the diff of this file is too big to display

yarn.lock

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc