Add type deprecated (ianstormtaylor#534)

* Add type deprecated

* Improve test description

* Reformat

* Validate passed struct

* Clean up

* Adapt code for master and improve tests

* Add doc

* Improve description

* Pass custom logging function with value and ctx

* Do not log if value is already unused

* Update documentation

* Adapt comment

* Adapt changes for branch main

* Improve comment

* Update index.ts

* Update utilities.md

* Update utilities.ts

* Update .eslintrc

Co-authored-by: Ian Storm Taylor <[email protected]>

Author: maxadv

.eslintrc

@@ -104,10 +104,6 @@
     "radix": "error",
     "spaced-comment": ["error", "always", { "exceptions": ["-"] }],
     "use-isnan": "error",
-    "valid-jsdoc": [
-      "error",
-      { "prefer": { "return": "returns" }, "requireReturn": false }
-    ],
     "valid-typeof": "error",
     "yield-star-spacing": ["error", "after"],
     "yoda": ["error", "never"]

docs/reference/utilities.md

@@ -17,6 +17,24 @@ assign(object({ id: string() }), object({ name: string() }))
 
 `assign` creates a new struct by mixing the properties of existing object structs, similar to JavaScript's native [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign).
 
+### `deprecated`
+
+```ts
+object({
+  id: number(),
+  full_name: string(),
+  name: deprecated(string(), (value, ctx) => {
+    console.warn(`${ctx.path} is deprecated, but value was '${value}'. Please use 'full_name' instead.`)
+  }),
+})
+```
+
+```ts
+{ id: 1, name: 'Jane' }
+```
+
+`deprecated` structs validate that a value matches a specific struct, or that it is `undefined`. But in addition, when the value is not `undefined`, it will call the `log` function you pass in so you can warn users that they're using a deprecated API.
+
 ### `dynamic`
 
 ```ts

src/structs/utilities.ts

@@ -66,6 +66,29 @@ export function define<T>(name: string, validator: Validator): Struct<T, null> {
   return new Struct({ type: name, schema: null, validator })
 }
 
+/**
+ * Create a new struct based on an existing struct, but the value is allowed to
+ * be `undefined`. `log` will be called if the value is not `undefined`.
+ */
+
+export function deprecated<T>(
+  struct: Struct<T>,
+  log: (value: unknown, ctx: Context) => void
+): Struct<T> {
+  return new Struct({
+    ...struct,
+    refiner: (value, ctx) => value === undefined || struct.refiner(value, ctx),
+    validator(value, ctx) {
+      if (value === undefined) {
+        return true
+      } else {
+        log(value, ctx)
+        return struct.validator(value, ctx)
+      }
+    },
+  })
+}
+
 /**
  * Create a struct with dynamic validation logic.
  *

test/index.ts

@@ -1,8 +1,15 @@
-import assert from 'assert'
+import assert, { CallTracker } from 'assert'
 import fs from 'fs'
 import { pick } from 'lodash'
 import { basename, extname, resolve } from 'path'
-import { assert as assertValue, create as createValue, StructError } from '..'
+import {
+  any,
+  assert as assertValue,
+  Context,
+  create as createValue,
+  deprecated,
+  StructError,
+} from '..'
 
 describe('superstruct', () => {
   describe('api', () => {
@@ -83,10 +90,40 @@ describe('superstruct', () => {
       })
     }
   })
+
+  describe('deprecated', () => {
+    it('does not log deprecated type if value is undefined', () => {
+      const tracker = new CallTracker()
+      const logSpy = buildSpyWithZeroCalls(tracker)
+      assertValue(undefined, deprecated(any(), logSpy))
+      tracker.verify()
+    })
+
+    it('logs deprecated type to passed function if value is present', () => {
+      const tracker = new CallTracker()
+      const fakeLog = (value: unknown, ctx: Context) => {}
+      const logSpy = tracker.calls(fakeLog, 1)
+      assertValue('present', deprecated(any(), logSpy))
+      tracker.verify()
+    })
+  })
 })
 
 /**
  * A helper for testing type signatures.
  */
 
 export function test<T>(fn: (x: unknown) => T) {}
+
+/**
+ * This emulates `tracker.calls(0)`.
+ *
+ * `CallTracker.calls` doesn't support passing `0`, therefore we expect it
+ * to be called once which is our call in this test. This proves that
+ * the following action didn't call it.
+ */
+function buildSpyWithZeroCalls(tracker: CallTracker) {
+  const logSpy = tracker.calls(1)
+  logSpy()
+  return logSpy
+}

test/typings/deprecated.ts

@@ -0,0 +1,14 @@
+import { assert, object, deprecated, any, Context } from '../..'
+import { test } from '..'
+
+test<unknown>((x) => {
+  const log = (value: unknown, ctx: Context) => {}
+  assert(x, deprecated(any(), log))
+  return x
+})
+
+test<{ a?: unknown }>((x) => {
+  const log = (value: unknown, ctx: Context) => {}
+  assert(x, object({ a: deprecated(any(), log) }))
+  return x
+})

test/validation/deprecated/invalid-null.ts

@@ -0,0 +1,15 @@
+import { deprecated, string } from '../../..'
+
+export const Struct = deprecated(string(), () => {})
+
+export const data = null
+
+export const failures = [
+  {
+    value: null,
+    type: 'string',
+    refinement: undefined,
+    path: [],
+    branch: [data],
+  },
+]

test/validation/deprecated/invalid-property.ts

@@ -0,0 +1,19 @@
+import { deprecated, number, object } from '../../..'
+
+export const Struct = object({
+  deprecatedKey: deprecated(number(), () => {}),
+})
+
+export const data = {
+  deprecatedKey: '42',
+}
+
+export const failures = [
+  {
+    value: '42',
+    type: 'number',
+    refinement: undefined,
+    path: ['deprecatedKey'],
+    branch: [data, data.deprecatedKey],
+  },
+]

test/validation/deprecated/invalid.ts

@@ -0,0 +1,15 @@
+import { deprecated, number } from '../../..'
+
+export const Struct = deprecated(number(), () => {})
+
+export const data = '42'
+
+export const failures = [
+  {
+    value: '42',
+    type: 'number',
+    refinement: undefined,
+    path: [],
+    branch: [data],
+  },
+]

test/validation/deprecated/valid-property.ts

@@ -0,0 +1,14 @@
+import { type, number, deprecated, any } from '../../..'
+
+export const Struct = type({
+  name: deprecated(any(), () => {}),
+  age: number(),
+})
+
+export const data = {
+  age: 42,
+}
+
+export const output = {
+  age: 42,
+}

test/validation/deprecated/valid-undefined.ts

@@ -0,0 +1,7 @@
+import { deprecated, number } from '../../..'
+
+export const Struct = deprecated(number(), () => {})
+
+export const data = undefined
+
+export const output = undefined

test/validation/deprecated/valid.ts

@@ -0,0 +1,7 @@
+import { deprecated, number } from '../../..'
+
+export const Struct = deprecated(number(), () => {})
+
+export const data = 42
+
+export const output = 42