You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: Changelog.md
+149
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,155 @@
2
2
3
3
This document maintains a list of changes to the `superstruct` package with each new version. Until `1.0.0` is released, breaking changes will be added as minor version bumps, and smaller changes and fixes won't be detailed.
4
4
5
+
### `0.10.0` — June 5, 2020
6
+
7
+
The `0.10` version is a complete overhaul with the goal of making Superstruct much simpler and easier to understand, and with complete support for runtime type signatures TypeScript.
8
+
9
+
This makes it much more powerful, however the core architecture has had to change to make it happen. It will still look very similar, but migrating between the versions _will be more work than usual_. There's no requirement to upgrade, although if you're using Superstruct in concert with TypeScript you will have a much better experience.
10
+
11
+
###### BREAKING
12
+
13
+
**All types are created from factories.** Previously depending on whether the type was a complex type or a scalar type they'd be defined different. Complex types used factories, whereas scalars used strings. Now all types are exposed as factories.
14
+
15
+
For example, previously:
16
+
17
+
```ts
18
+
import { struct } from'superstruct'
19
+
20
+
const User =struct.object({
21
+
name: 'string',
22
+
age: 'number',
23
+
})
24
+
```
25
+
26
+
Now becomes:
27
+
28
+
```ts
29
+
import { object, string, number } from'superstruct'
30
+
31
+
const User =object({
32
+
name: string(),
33
+
age: number(),
34
+
})
35
+
```
36
+
37
+
**Custom scalars are no longer pre-defined as strings.** Previously, you would define all of your "custom" types in a single place in your codebase and then refer to them in structs later on with a string value. This worked, but added a layer of unnecessary indirection, and made it impossible to accomodate runtime type signatures.
38
+
39
+
In the new version, custom types are defined extremely similarly to non-custom types. And this has the added benefit that you can easily trace the custom type definitions by just following `import` statements.
40
+
41
+
Here's how it used to work:
42
+
43
+
```ts
44
+
import { superstruct } from'superstruct'
45
+
importisEmailfrom'is-email'
46
+
47
+
const struct =superstruct({
48
+
types: {
49
+
email: isEmail,
50
+
},
51
+
})
52
+
53
+
const Email =struct('email')
54
+
```
55
+
56
+
And here's what it would look like now:
57
+
58
+
```ts
59
+
import { struct } from'superstruct'
60
+
importisEmailfrom'is-email'
61
+
62
+
const Email =struct('email', isEmail)
63
+
```
64
+
65
+
**Validation logic has been moved to helper functions.** Previously the `assert` and `is` helpers lived on the struct objects themselves. Now, these functions have been extracted into separate helpers. This was unfortunately necessary to work around limitations in TypeScript's `asserts` keyword.
66
+
67
+
For example, before:
68
+
69
+
```ts
70
+
User.assert(data)
71
+
```
72
+
73
+
Now would be:
74
+
75
+
```ts
76
+
import { assert } from'superstruct'
77
+
78
+
assert(data, User)
79
+
```
80
+
81
+
**Coercion is now separate from validation.** Previously there was native logic for handling default values for structs when validating them. This has been abstracted into the ability to define _any_ custom coercion logic for structs, and it has been separate from validation to make it very clear when data can change and when it cannot.
82
+
83
+
For example, previously:
84
+
85
+
```ts
86
+
const output =User.assert(input)
87
+
```
88
+
89
+
Would now be:
90
+
91
+
```ts
92
+
input=coerce(input, User)
93
+
assert(input, User)
94
+
```
95
+
96
+
With two clear steps. The `coerce` step is the only time that data will be transformed at all by coercion logic, and the `assert` step no longer needs to return any values. This makes it easy to do things like:
97
+
98
+
```ts
99
+
if (is(input, User)) {
100
+
// ...
101
+
}
102
+
```
103
+
104
+
**Validation context is now a dictionary of properties.** Previously when performing complex validation logic that was dependent on other properties on the root object, you could use the second `branch` argument to the validation function. This argument has been changed to be a `context` dictionary with more information. The same branch argument can now be accessed as `context.branch`, along with the new information.
105
+
106
+
**Unknown properties of objects now have a `'never'` type.** Previously unknown properties would throw errors with `type === null`, however the newly introduced `'never'` type is now used instead.
107
+
108
+
**The `function` struct was removed.** There's no longer any need for it, because you can define one-off validations directly with the custom `struct` factory.
109
+
110
+
**Defaults are now defined with a separate coercion helper.** Previously all structs took a second argument that defined the default value to use if an `undefined` value was present. This has been pulled out into a separate helper now to clearly distinguish coercion logic.
111
+
112
+
For example, previously you'd do:
113
+
114
+
```ts
115
+
const Article =struct.object(
116
+
{
117
+
title: 'string',
118
+
},
119
+
{
120
+
title: 'Untitled',
121
+
}
122
+
)
123
+
```
124
+
125
+
Whereas now you'd do:
126
+
127
+
```ts
128
+
const Article =defaulted(
129
+
object({
130
+
title: string(),
131
+
}),
132
+
{
133
+
title: 'Untitled',
134
+
}
135
+
)
136
+
```
137
+
138
+
**Optional arguments are now defined with a seperate factory.** Similarly to defaults, there is a new `optional` factory for defined values that can also be `undefined`.
// This will throw when the data is invalid, and return the data otherwise.
74
-
// If you'd rather not throw, use `Struct.validate()` or `Struct.test()`.
70
+
assert(data, Article)
71
+
// This will throw an error when the data is invalid.
72
+
// If you'd rather not throw, you can use `is()` or `validate()`.
75
73
```
76
74
77
-
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:
75
+
Superstruct comes with validators for all common JavaScript data types out of the box. And you can also define your own custom validations:
78
76
79
77
```js
80
-
import { superstruct } from'superstruct'
78
+
import { is, struct, object, string } from'superstruct'
// You can apply the defaults to your data while validating.
117
+
const user =coerce(data, User)
118
+
// {
119
+
// id: 1,
120
+
// name: 'Jane',
121
+
// }
103
122
```
104
123
105
-
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).
124
+
And if you use TypeScript, Superstruct automatically ensures that your data has proper typings whenever you validate it:
125
+
126
+
```ts
127
+
import { is, object, number, string } from'superstruct'
128
+
129
+
const User =object({
130
+
id: number(),
131
+
name: string()
132
+
})
133
+
134
+
const data:unknown= { ... }
135
+
136
+
if (is(data, User)) {
137
+
// TypeScript knows the shape of `data` here, so it is safe to access
138
+
// properties like `data.id` and `data.name`.
139
+
}
140
+
```
141
+
142
+
Superstruct supports more complex use cases too like defining arrays or nested objects, composing structs inside each other, returning errors instead of throwing them, and more! For more information read the full [Documentation](#documentation).
106
143
107
144
<br/>
108
145
@@ -138,13 +175,9 @@ Which brings me to how Superstruct solves these issues...
138
175
139
176
3.**Composable interfaces.** Superstruct interfaces are composable, so you can break down commonly-repeated pieces of data into components, and compose them to build up the more complex objects.
140
177
141
-
4.**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.
142
-
143
-
5.**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.
144
-
145
-
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!
178
+
4.**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!
146
179
147
-
7.**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.
180
+
5.**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.
148
181
149
182
<br/>
150
183
@@ -167,6 +200,7 @@ Superstruct's API is very flexible, allowing it to be used for a variety of use
0 commit comments