A simple and composable way to validate data in JavaScript (and TypeScript).

The current type definitions located at @types/superstruct are good. However, they do not check the type of your struct at compile time, leading to poorer autocomplete as the shape of your struct is not known to TypeScript. A major reason for this is TypeScript's widening of string literals in non-constant contexts. For example, the type of the following struct definition:

const def = {
  someProp: 'number'
}

is known as:

{someProp: string}

rather than

{someProp: 'number'}

This makes it near impossible to write any kind of mapped type that would be valid to your struct. In my research, I have discovered two possible solutions rather than just defaulting to any: a shape-only type and more specific struct definitions.

With a shape only type, upon constructing a struct with this definition:

const definition = {
  someProp: 'number',
  someObject: {
    anotherProp: 'boolean?'
  }
}

you would receive a validation function that has the following type:

(objectToTest: any) => {someProp: any, someObject: {anotherProp: any}}

This would at least enable autocomplete with your struct's properties, preventing typos at compile time. This does not protect against a property possibly being null (for example, struct.someObject.anotherProp can be null in the above example) nor does it actually enforce the types (i.e. number) you've already defined in your struct.

The other option is to use string literal narrowing in your struct definitions, or const enums. For example, if we define a const enum like this:

const enum Types {
  String = 'string',
  OptionalString = 'string?'
  Number = 'number',
  OptionalNumber = 'number?'
}

it becomes possible to write a mapped type such that a struct definition such as this:

const definition = {
  someProp: Types.Number
}

returns a struct function with the following type:

(objectToTest: any) => {someProp: number}

This also works if you force the compiler to not widen the type. The following definition will produce the same type:

const definition = {
  someProp: 'number' as 'number'
}

The nice thing about using a const enum is that is does not force this library to switch to TypeScript, rather, the enum constants themselves are inlined upon compilation rather than using a static class.

I'm looking here to start a discussion about how to implement such a feature in the typings, and whether any of these solutions I've thought of so far are any good.

Why?

Rollup is known for consistently producing the smallest bundles. In this case, the biggest reason is because Browserify's overhead is much bigger than Rollup. Rollup also inlines its imports directly within the bundles, whereas Browserify leaves require statements, each of which needs its own interop wrapper.

...That's also to say that the Browserify build has to deal with require statements at runtime, which seems like a silly step to take since we're pre-compiling anyway.

Bublé also consistently produces smaller ES5 code and with less configuration. It exposes its own buble/register which is now in the tests. Because of this, the tests' elapsed time has dropped from ~750ms to ~115ms!

Commands

As for the actual "build" command, I imported a builder.js file I use across a bunch of my modules. It produces 3 files in 3 different formats:

• ES Module: lib/superstruct.es.js
• CommonJS: lib/superstruct.js
• UMD: lib/superstruct.min.js

I've updated package.json's entries to expose these three correctly.

The main benefit here is that Webpack/Rollup users get to use partial imports for free, and Node.js servers can use the CJS module (sans requires!) as normal.

The "watch" command was updated to use Rollup directly. Nothing extra is needed. I have it producing the CJS/main file only. Don't think the others are needed here.

Results

The final GZIP size of the UMD file is 5.11 kB! 🎉 Of course, this number is actually smaller if you compress the other two files (no UMD header).

Suggestions

• It's a personal thing, I know, but the "clean" command seems useless to me. 😜

• I'd also remove .npmignore in favor of specifying a files key within package.json. I personally only allow the lib directory -- imo, devs can lookup the repo for docs & examples. But you can definitely include docs and examples here too if you want. 😄

Closes #12 because Rollup handles this internally.

Sorry if this was more of an overhaul than you would have liked @ianstormtaylor 😅

Importing @solana/web3.js in React Native throws the following error.

error: Error: While trying to resolve module `superstruct` from file `/Users/sluscher/mobile-wallet-adapter/js/node_modules/@solana/web3.js/lib/index.browser.cjs.js`, the package `/Users/sluscher/mobile-wallet-adapter/js/node_modules/superstruct/package.json` was successfully found. However, this package itself specifies a `main` module field that could not be resolved (`/Users/sluscher/mobile-wallet-adapter/js/node_modules/superstruct/lib/index.cjs`. Indeed, none of these files exist:

  * /Users/sluscher/mobile-wallet-adapter/js/node_modules/superstruct/lib/index.cjs(.native|.android.js|.native.js|.js|.android.json|.native.json|.json|.android.ts|.native.ts|.ts|.android.tsx|.native.tsx|.tsx)

You can see that the React Native packager expects a .js extension in addition to .cjs

If superstruct could rename the CommonJS bundles from .cjs to .cjs.js that would make it Just Work™ for React Native folks!

More details on the problem here, if you're interested: https://github.com/facebook/metro/issues/535

Hei,

I'm trying to plug supertruct to a react-native app, but i'm getting this error

error: Error: While trying to resolve module `superstruct` from file `validation.js`, the package `node_modules/superstruct/package.json` was successfully found. 
However, this package itself specifies a `main` module field that could not be resolved (`node_modules/superstruct/index.cjs`. Indeed, none of these files exist:

Let's say I have a struct: struct.object({foo: 'string'})
Then I pass an object: s.validate({ foo: 'bar', bar: 'foo' })
Currently I am receiving an error with path [ 'bar' ] and message Expected a value of typeundefinedforbarbut received"foo".

I think that this behavior is incorrect, and the path should be empty array, i.e. the error belongs to whole struct and not to unspecified property. And the message should be adjusted accordingly.

The following use case illustrates why I think so. I face this situation quite often. There is a form that receives data from backend, user edits the data, then submits it back. The thing is that what backend sends, what backend expects to receive, and what the form internally uses sometimes have different shapes (the form needs some extra data to look nice, or rich text needs to be transformed from markdown to internal representation, etc...). This leads to unspecified properties, and results in validation error. UI then checks paths of errors and displays them on corresponding UI controls. Those errors with empty path array (like multi-field errors) are then displayed in an ugly red box for whole form errors. The problem with current error paths is that there is no way I can know that unspecified fields errors belong to whole form, they look like they belong to particular UI control, but there is no such control on the form.

'use strict';
const { struct } = require('../lib/superstruct/lib/index');
const Article = struct({
  id: 'number',
  author: {
    id: 'number',
  },
});
const data = {
  id: 34,
  author: {
    id: 1,
    test: undefined,
  },
};
const article = Article(data);
console.log('article', article);

I use the struct to validate data from excel, some unsed keys are set to undefined, and I get an error like : Expected a value of type undefined for author.test but received undefined

I try to partial, but it is not recursive. so I create this issues and a pull request.

Hey

I checked the docs, but didn't find any info if this library is supposed to be used only to validate types of data or it can be used for other validations.

For example, I can check if value is a number. Is it possible and how to check, if this value is less than 100 or more than 6?

Hi 👋 really digging this library for validating objects

My only question is about customizing paths when creating types via superstruct

const struct = superstruct({
  types: {
    location: value => {
      const empty = Object.keys(value).reduce((acc, key) => {
        return value[key].state === null && value[key].county === null
          ? acc.concat(key)
          : acc;
      }, []);
      const str = empty.join(", ");
      return str === ""
        ? true
        : `Either state or county for ${str} is required`;
    },
    duplicate: val => {
      const mmap = Object.keys(val).reduce((map, key) => {
        CHECK_LIST.forEach(item => {
          if (val[key][item] !== "" && val[key][item] != null) {
            map.set(`${item}.${val[key][item]}`, `${key}.${item}`);
          }
        });
        return map;
      }, new MultiMap());
      
      const gatherDuplicates = mmap
        .values()
        .reduce((acc, x) => (x.length >= 2 ? acc.concat(x) : acc), []);
        
      const error = `The following keys are duplicates: ${gatherDuplicates.join(", ")}`

      return gatherDuplicates.length > 0 ? error : true;
    }
  }
});

const Location = struct('location&duplicate')

const data = {
  123: {
    state: null,
    county: null
  },
  456: {
    state: null,
    county: null
  }
}

Location.validate(data)

Currently the above code checks if the dynamic keys have either state or county filled in and then if either state or county is a duplicate

Returning custom messages works great but for whatever reason the paths array is always empty which brings me to my question of customizing paths because i have all of the information i need to create a path but no obvious way of doing, unless I am missing something ?

Which versions of node are supported? Currently due to dependencies only node 8+ is supported, is that intended?

error [email protected]: The engine "node" is incompatible with this module. Expected version ">=8".

const struct = object({text: enums(["foo", "bar"])})
const {text}  = create({ text: "foo"}, struct)

the text variable is given a type of string while I am expecting "foo" | "bar". I can get around the problem with the more verbose union([literal("foo"), literal("bar")])

Right now, it's impossible to coerce a nested structure, both because coerce() also validates (#467 ) but also because coerce() only runs on the top-level object. For instance, coerce({}, type({...props})) will fail, even if all props have coercions, because they never run.

coerce() should function parallel to check() (preferably with a context object). In the case of validate-with-coerce, they could still run like now, in tandem.

Bumps eslint from 7.32.0 to 8.31.0.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

I cannot figure out how to describe generics with conditionals. This might be a limitation by TypeScript though.

Given the following types:

enum Types {
  One = "one",
  Two = "two",
}

type Validating<T extends Types = Types> = {
  type: T;
  value: T extends Types.One ? string : never;
};

I can't figure out how to type value in Validating. This is my general idea:

const Validating: Describe<Validating> = union([
  object({
    type: literal(Types.One),
    value: string(),
  }),
  object({
    type: literal(Types.Two),
  }),
]);

assert({ type: Types.One, value: "Value!" }, Validating);
assert({ type: Types.Two }, Validating);

But this does not compile, giving the following error:

Type 'Struct<{ type: Types.One; value: string; } | { type: Types.Two; }, null>' is not assignable to type 'Describe<Validating<Types>>'.
  Types of property 'TYPE' are incompatible.
    Type '{ type: Types.One; value: string; } | { type: Types.Two; }' is not assignable to type 'Validating<Types>'.
      Type '{ type: Types.Two; }' is not assignable to type 'Validating<Types>'.

I also had a second idea which is even more broken, but is nicer if possible.

const Validating: Describe<Validating> = dynamic((v: any) =>
  object({
    type: literal(Types.One),
    value: v.type === Types.One ? string() : never(),
  }),
);

assert({ type: Types.One, value: "Value!" }, Validating);
assert({ type: Types.Two }, Validating);

I think this is related to #724, but not quite the same.

First of all, thank you for this convenient tree-shakeable lib!

Sometimes we don't need to know, what the keys are in our object, but only their types E.g. We keep addresses, added by user in structure like that:

addresses: {
  [addressName: string]: string
}

TS allows us to do it

What if to add similar behavior in object structure, using a Symbol for that. Symbol lets you distinguish this props from any others:

// Inside Superstruct lib
export const anyProp = Symbol()
...
const isAnyProp = key === anyProp
...

// On Superstruct's user side
import { object, anyProp } from 'superstruct'

const Addresses = object({
  requiredAddressField: string,
  [anyProp]: string
})

This will help for debugging when the assert has failed.

When a value is an object, the message for failure contains [object Object].

Adding a stringify on the value if its type is object seems like the quickiest win for easier debugging.

The Infer function is great because it allows us to get the output types of a given struct. However, it would also be great to be able to get the input types of a given struct. I'll give an example of the difference:

The following struct will always output a number.

const MyNumber = coerce(number(), string(), (value) => parseFloat(value))
type OutputType = number // generated by Infer

However, it can accept numbers & strings. So the input type would be:

type InputType = string | number

I need a way to Infer the input type of a struct. Also, I think this would be a great addition to the already great lib.