updating docs

Author: dwightjack

Diff for: .prettierrc.cjs

@@ -0,0 +1,11 @@
+/**
+ * @see https://prettier.io/docs/en/configuration.html
+ * @type {import("prettier").Config}
+ */
+export default {
+  printWidth: 80,
+  trailingComma: 'all',
+  arrowParens: 'always',
+  semi: false,
+  singleQuote: true,
+}

Diff for: .prettierrc.mjs

@@ -5,6 +5,9 @@
   "[ts]": {
     "editor.formatOnSave": false
   },
+  "[markdown]": {
+    "editor.formatOnSave": true
+  },
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": "explicit"
   }

Diff for: .vscode/settings.json

@@ -330,6 +330,30 @@ describe('`toValidableType()`', () => {
   })
 })
 
+describe('`deepClone()`', () => {
+  it('deep clones an object', () => {
+    const obj = { a: 1, b: { c: 2 } }
+
+    const clone = utils.deepClone(obj)
+
+    expect(clone).not.toBe(obj)
+
+    clone.b.c = 3
+    expect(obj.b.c).not.toBe(clone.b.c)
+  })
+
+  it('deep clones an array', () => {
+    const arr = [{ b: { c: 2 } }]
+    const clone = utils.deepClone(arr)
+
+    expect(clone).not.toBe(arr)
+
+    clone[0].b.c = 3
+
+    expect(arr[0].b.c).not.toBe(clone[0].b.c)
+  })
+})
+
 describe('`clone()`', () => {
   it('clones an object', () => {
     const obj = { a: true }

Diff for: packages/core/__tests__/utils.test.ts

@@ -0,0 +1,18 @@
+/**
+ * Support globalThis in E2019 and lower
+ * @see https://mathiasbynens.be/notes/globalthis
+ */
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+;(function () {
+  if (typeof globalThis === 'object') return
+  Object.defineProperty(Object.prototype, '__magic__', {
+    get: function () {
+      return this
+    },
+    configurable: true, // This makes it possible to `delete` the getter later.
+  })
+  // @ts-expect-error
+  __magic__.globalThis = __magic__ // lolwat
+  // @ts-expect-error
+  delete Object.prototype.__magic__
+})()

Diff for: packages/core/src/global-this.ts

@@ -1,5 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { isPlainObject } from './is-plain-obj'
+import './global-this'
 import { typeDefaults } from './sensibles'
 import { config } from './config'
 import type { VueTypesDefaults } from './types'
@@ -12,6 +13,19 @@ const isArray =
     return Object.prototype.toString.call(value) === '[object Array]'
   }
 
+function deepClone<T>(input: T): T {
+  if ('structuredClone' in globalThis) {
+    return structuredClone(input)
+  }
+  if (Array.isArray(input)) {
+    return [...input] as T
+  }
+  if (isPlainObject(input)) {
+    return Object.assign({}, input)
+  }
+  return input
+}
+
 function type(name: string, props: any = {}, validable = false): any {
   const descriptors: PropertyDescriptorMap = {
     _vueTypes_name: {
@@ -29,9 +43,9 @@ function type(name: string, props: any = {}, validable = false): any {
           return this
         }
         if (isArray(v)) {
-          t.default = () => [].concat(v as any)
+          t.default = () => deepClone(v)
         } else if (isPlainObject(v)) {
-          t.default = () => Object.assign({}, v)
+          t.default = () => deepClone(v)
         } else {
           t.default = v
         }

Diff for: packages/core/src/shim.ts

@@ -1,3 +1,4 @@
+import './global-this'
 import { config } from './config'
 import {
   VueTypeDef,
@@ -36,6 +37,19 @@ export function getNativeType(value: any): string {
   return match ? match[1].replace(/^Async/, '') : ''
 }
 
+export function deepClone<T>(input: T): T {
+  if ('structuredClone' in globalThis) {
+    return structuredClone(input)
+  }
+  if (Array.isArray(input)) {
+    return [...input] as T
+  }
+  if (isPlainObject(input)) {
+    return Object.assign({}, input)
+  }
+  return input
+}
+
 /**
  * No-op function
  */
@@ -295,9 +309,9 @@ export function toType<T = any>(name: string, obj: PropOptions<T>) {
           return this
         }
         if (isArray(def)) {
-          this.default = () => [...def]
+          this.default = () => deepClone(def)
         } else if (isPlainObject(def)) {
-          this.default = () => Object.assign({}, def)
+          this.default = () => deepClone(def)
         } else {
           this.default = def
         }

Diff for: packages/core/src/utils.ts

@@ -252,7 +252,7 @@ props: {
 }
 ```
 
-::: warning
+::: warning {id=oneof-warning}
 
 Note that union types don't put any constrain on the presence of all of their members in the validation array. This can lead to runtime bugs not detected by the type checker:
 

Diff for: packages/docs/advanced/typescript.md

@@ -1,16 +1,25 @@
 ---
 ---
+<script setup>
+import CodeExample from '../components/CodeExample.vue'
+</script>
 
 # Namespaced Usage
 
 The default export of `vue-types` exposes an ES6 class object that mimics React prop-type.
 
-The class object exposes both [native](/guide/validators.html#native-validators) and [custom](/guide/validators.html#custom-validators) validators.
+The class object exposes both [native](./validators.md#native-validators) and [custom](./validators.md#custom-validators) validators.
+
+::: tip
+While namespaced usage is not deprecated, [named validators](./validators.md) are usually a better and more type-safe option for your project.
+:::
 
 ## Native Validators
 
 Native validators are exposed as static getter factories:
 
+<CodeExample>
+
 ```js
 import VueTypes from 'vue-types'
 
@@ -20,11 +29,26 @@ export default {
   },
 }
 ```
+---
+```js
+import VueTypes from 'vue-types'
 
-The main difference between namespaced native validators and those directly imported from the library is that the former come (usually) with a default value already defined.
+defineProps({
+  message: VueTypes.string.isRequired,
+})
+```
+</CodeExample>
+
+::: warning NOTE
+
+The main difference between namespaced native validators and those directly imported from the library is that the former come (usually) **with a default value already defined** (see table below).
+
+:::
 
 <div id="default-values">
 
+### Native validators default values
+
 | Validator | Default    | `validate()` method |
 | --------- | ---------- | ------------------- |
 | any       | -          | yes                 |
@@ -53,7 +77,7 @@ const stringProp = VueTypes.string
 // stringProp ===  { type: String, default : '' }
 ```
 
-## Native Types Configuration
+## Native types configuration
 
 All native validators (with the exception of `any` and `symbol`) come with a sensible default value. To customize or disable that value, you can set the global option `VueTypes.sensibleDefaults`: