docs: add keyword tables, more content (#1236)

arktypeio · Dec 24, 2024 · 2569bde · 2569bde
1 parent 1fafb80
commit 2569bde
Show file tree

Hide file tree

Showing 40 changed files with 243 additions and 189 deletions.
diff --git a/ark/attest/package.json b/ark/attest/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@ark/attest",
-	"version": "0.33.0",
+	"version": "0.34.0",
 	"license": "MIT",
 	"author": {
 		"name": "David Blass",

diff --git a/ark/docs/app/discord/page.tsx b/ark/docs/app/discord/page.tsx
@@ -0,0 +1,11 @@
+"use client"
+
+import { useEffect } from "react"
+
+export default () => {
+	useEffect(() => {
+		window.location.href = "https://discord.com/invite/xEzdc3fJQC"
+	}, [])
+
+	return null
+}
diff --git a/ark/docs/components/AutoDocs.tsx b/ark/docs/components/AutoDocs.tsx
diff --git a/ark/docs/components/KeywordTable.tsx b/ark/docs/components/KeywordTable.tsx
@@ -0,0 +1,78 @@
+import { append, entriesOf, flatMorph } from "@ark/util"
+import { ark, Generic } from "arktype"
+import { arkPrototypes } from "arktype/internal/keywords/constructors.ts"
+import type { JSX } from "react"
+
+const tableNames = [
+	"string",
+	"number",
+	"other",
+	"object",
+	"array",
+	"FormData",
+	"TypedArray",
+	"instanceof",
+	"generic"
+] as const
+
+type TableName = (typeof tableNames)[number]
+
+const tableRowsByName = flatMorph(tableNames, (i, name) => [
+	name,
+	[] as JSX.Element[]
+])
+
+entriesOf(ark.internal.resolutions)
+	.map(
+		([alias, v]) =>
+			[alias.endsWith(".root") ? alias.slice(0, -5) : alias, v] as const
+	)
+	.sort((l, r) => (l[0] < r[0] ? -1 : 1))
+	.forEach(([alias, v]) => {
+		// should not occur, only for temporary resolutions of cyclic definition
+		if (typeof v === "string") return
+
+		const name =
+			alias.startsWith("string") ? "string"
+			: alias.startsWith("number") ? "number"
+			: alias.startsWith("FormData") ? "FormData"
+			: alias.startsWith("Array") ? "array"
+			: alias.startsWith("object") ? "object"
+			: alias.startsWith("TypedArray") ? "TypedArray"
+			: v instanceof Generic ? "generic"
+			: alias in arkPrototypes ? "instanceof"
+			: "other"
+
+		tableRowsByName[name] = append(
+			tableRowsByName[name],
+			<tr key={alias}>
+				<td>{alias}</td>
+				<td>{v.description}</td>
+			</tr>
+		)
+	})
+
+export type KeywordTableProps = {
+	name: TableName
+	rows: JSX.Element[]
+}
+
+export const KeywordTable = ({ name, rows }: KeywordTableProps) => (
+	<>
+		<h2>{name}</h2>
+		<table>
+			<thead>
+				<tr>
+					<th className="font-bold">Alias</th>
+					<th className="font-bold">Description</th>
+				</tr>
+			</thead>
+			<tbody>{...rows}</tbody>
+		</table>
+	</>
+)
+
+export const AllKeywordTables = () =>
+	tableNames.map(name => (
+		<KeywordTable name={name} rows={tableRowsByName[name]} />
+	))
diff --git a/ark/docs/components/snippets/contentsById.ts b/ark/docs/components/snippets/contentsById.ts
@@ -0,0 +1,12 @@
+export default {
+	betterErrors:
+		'import { type, type ArkErrors } from "arktype"\n\nconst user = type({\n\tname: "string",\n\tplatform: "\'android\' | \'ios\'",\n\t"versions?": "(number | string)[]"\n})\n\ninterface RuntimeErrors extends ArkErrors {\n\t/**platform must be "android" or "ios" (was "enigma")\nversions[2] must be a number or a string (was bigint)*/\n\tsummary: string\n}\n\nconst narrowMessage = (e: ArkErrors): e is RuntimeErrors => true\n\n// ---cut---\nconst out = user({\n\tname: "Alan Turing",\n\tplatform: "enigma",\n\tversions: [0, "1", 0n]\n})\n\nif (out instanceof type.errors) {\n\t// ---cut-start---\n\tif (!narrowMessage(out)) throw new Error()\n\t// ---cut-end---\n\t// hover summary to see validation errors\n\tconsole.error(out.summary)\n}\n',
+	clarityAndConcision:
+		'// @errors: 2322\nimport { type } from "arktype"\n// this file is written in JS so that it can include a syntax error\n// without creating a type error while still displaying the error in twoslash\n// ---cut---\n// hover me\nconst user = type({\n\tname: "string",\n\tplatform: "\'android\' | \'ios\'",\n\t"versions?": "number | string)[]"\n})\n',
+	deepIntrospectability:
+		'import { type } from "arktype"\n\nconst user = type({\n\tname: "string",\n\tdevice: {\n\t\tplatform: "\'android\' | \'ios\'",\n\t\t"version?": "number | string"\n\t}\n})\n\n// ---cut---\nuser.extends("object") // true\nuser.extends("string") // false\n// true (string is narrower than unknown)\nuser.extends({\n\tname: "unknown"\n})\n// false (string is wider than "Alan")\nuser.extends({\n\tname: "\'Alan\'"\n})\n',
+	intrinsicOptimization:
+		'import { type } from "arktype"\n// prettier-ignore\n// ---cut---\n// all unions are optimally discriminated\n// even if multiple/nested paths are needed\nconst account = type({\n\tkind: "\'admin\'",\n\t"powers?": "string[]"\n}).or({\n\tkind: "\'superadmin\'",\n\t"superpowers?": "string[]"\n}).or({\n\tkind: "\'pleb\'"\n})\n',
+	unparalleledDx:
+		'// @noErrors\nimport { type } from "arktype"\n// prettier-ignore\n// ---cut---\nconst user = type({\n\tname: "string",\n\tplatform: "\'android\' | \'ios\'",\n\t"version?": "number | s"\n\t//                     ^|\n})\n'
+}
diff --git a/ark/docs/content/docs/about.mdx b/ark/docs/content/docs/about.mdx
diff --git a/ark/docs/content/docs/auto.mdx b/ark/docs/content/docs/auto.mdx
diff --git a/ark/docs/content/docs/configuration/index.mdx b/ark/docs/content/docs/configuration/index.mdx
@@ -8,7 +8,7 @@ title: Configuration
 
 ### Clone
 
-By default, before a [morph](/intro/morphs-and-more) is applied, ArkType will deeply clone the original input value with a built-in `deepClone` function that tries to make reasonable assumptions about preserving prototypes etc. The implementation of `deepClone` can be found [here](https://github.com/arktypeio/arktype/blob/main/ark/util/clone.ts).
+By default, before a [morph](/docs/intro/morphs-and-more) is applied, ArkType will deeply clone the original input value with a built-in `deepClone` function that tries to make reasonable assumptions about preserving prototypes etc. The implementation of `deepClone` can be found [here](https://github.com/arktypeio/arktype/blob/main/ark/util/clone.ts).
 
 You can provide an alternate clone implementation to the `clone` config option.
 

diff --git a/ark/docs/content/docs/definitions.mdx b/ark/docs/content/docs/definitions.mdx
@@ -1,7 +1,5 @@
 ---
 title: Definitions
-sidebar:
-  order: 1
 ---
 
 import { SyntaxTab, SyntaxTabs } from "../../components/SyntaxTabs.tsx"

diff --git a/ark/docs/content/docs/expressions/index.mdx b/ark/docs/content/docs/expressions/index.mdx
@@ -150,7 +150,7 @@ const myObject = type({
 
 ### Narrow
 
-Narrow expressions allow you to add custom validation logic and error messages. You can read more about them in [their intro section](/intro/adding-constraints#narrow).
+Narrow expressions allow you to add custom validation logic and error messages. You can read more about them in [their intro section](/docs/intro/adding-constraints#narrow).
 
 <SyntaxTabs>
     <SyntaxTab fluent>
@@ -291,7 +291,7 @@ const arkString = type(
 
 ### Morph
 
-Morphs allow you to transform your data after it is validated. You can read more about them in [their intro section](/intro/morphs-and-more/).
+Morphs allow you to transform your data after it is validated. You can read more about them in [their intro section](/docs/intro/morphs-and-more/).
 
 <SyntaxTabs>
     <SyntaxTab fluent>
@@ -325,7 +325,7 @@ const trimStringStart = type("string", "=>", str => str.trimStart())
 
 ### Unit
 
-While embedded [literal syntax](/literals) is usually ideal for defining exact primitive values, `===` and `type.unit` can be helpful for referencing a non-serialiazable value like a `symbol` from your type.
+While embedded [literal syntax](/docs/primitives#number-literals) is usually ideal for defining exact primitive values, `===` and `type.unit` can be helpful for referencing a non-serialiazable value like a `symbol` from your type.
 
 <SyntaxTabs>
 

diff --git a/ark/docs/content/docs/faq.mdx b/ark/docs/content/docs/faq.mdx
@@ -1,7 +1,5 @@
 ---
 title: FAQ
-sidebar:
-  order: 4
 ---
 
 ### Why do I see type errors in an ArkType package in `node_modules`?

diff --git a/ark/docs/content/docs/intro/adding-constraints.mdx b/ark/docs/content/docs/intro/adding-constraints.mdx
@@ -1,7 +1,5 @@
 ---
 title: Adding Constraints
-sidebar:
-  order: 3
 ---
 
 TypeScript is extremely versatile for representing types like `string` or `number`, but what about `email` or `integer less than 100`?

diff --git a/ark/docs/content/docs/intro/morphs-and-more.mdx b/ark/docs/content/docs/intro/morphs-and-more.mdx
@@ -1,7 +1,5 @@
 ---
 title: Morphs & More
-sidebar:
-  order: 4
 ---
 
 Sometimes, data at the boundaries of your code requires more than validation before it's ready to use.

diff --git a/ark/docs/content/docs/intro/setup.mdx b/ark/docs/content/docs/intro/setup.mdx
@@ -1,7 +1,5 @@
 ---
 title: Setup
-sidebar:
-  order: 1
 ---
 
 import { Tab, Tabs } from "fumadocs-ui/components/tabs"
@@ -16,9 +14,9 @@ You'll also need...
 - TypeScript version `>=5.1`.
 - A `package.json` with `"type": "module"` (or an environment that supports ESM imports)
 - A `tsconfig.json` with...
-  - [`strict`](https://www.typescriptlang.org/tsconfig#strict) or [`strictNullChecks`](https://www.typescriptlang.org/tsconfig/#strictNullChecks) (**required**)
-  - [`skipLibCheck`](https://www.typescriptlang.org/tsconfig/#exactOptionalPropertyTypes) (strongly recommended, see [FAQ](/reference/faq#why-do-i-see-type-errors-in-an-arktype-package-in-node_modules))
-  - [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig/#exactOptionalPropertyTypes) (recommended)
+  - [`strict`](https://www.typescriptlang.org/tsconfig#strict) or [`strictNullChecks`](https://www.typescriptlang.org/tsconfig#strictNullChecks) (**required**)
+  - [`skipLibCheck`](https://www.typescriptlang.org/tsconfig#skipLibCheck) (strongly recommended, see [FAQ](/docs/faq#why-do-i-see-type-errors-in-an-arktype-package-in-node_modules))
+  - [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) (recommended)
 
 ## VSCode
 

diff --git a/ark/docs/content/docs/intro/your-first-type.mdx b/ark/docs/content/docs/intro/your-first-type.mdx
@@ -1,7 +1,5 @@
 ---
 title: Your First Type
-sidebar:
-  order: 2
 ---
 
 If you already know TypeScript, congratulations- you just learned most of ArkType's syntax 🎉

diff --git a/ark/docs/content/docs/keywords.mdx b/ark/docs/content/docs/keywords.mdx
@@ -3,6 +3,7 @@ title: Keywords
 ---
 
 import { Asterisk } from "../../components/Asterisk.tsx"
+import { AllKeywordTables } from "../../components/KeywordTable.tsx"
 import { SyntaxTab, SyntaxTabs } from "../../components/SyntaxTabs.tsx"
 
 ### TypeScript
@@ -79,3 +80,9 @@ All builtin keywords and modules are available in `type.keywords`.
     </SyntaxTab>
 
 </SyntaxTabs>
+
+### All Keywords
+
+This table includes all keywords available in default `type` API. To define your own string-embeddable keywords, see [scopes](/docs/scopes).
+
+<AllKeywordTables />
diff --git a/ark/docs/content/docs/meta.json b/ark/docs/content/docs/meta.json
@@ -10,7 +10,6 @@
 		"integrations",
 		"scopes",
 		"generics",
-		"faq",
-		"about"
+		"faq"
 	]
 }
diff --git a/ark/docs/content/docs/objects/arrays/meta.json b/ark/docs/content/docs/objects/arrays/meta.json
@@ -2,10 +2,10 @@
 	"title": "arrays and tuples",
 	"pages": [
 		"lengths",
-		"[prefix](/docs/objects#arrays/prefix)",
-		"[optional](/docs/objects#arrays/optional)",
-		"[defaultable](/docs/objects#arrays/defaultable)",
-		"[variadic](/docs/objects#arrays/variadic)",
-		"[postfix](/docs/objects#arrays/postfix)"
+		"[prefix](/docs/objects#arrays-prefix)",
+		"[optional](/docs/objects#arrays-optional)",
+		"[defaultable](/docs/objects#arrays-defaultable)",
+		"[variadic](/docs/objects#arrays-variadic)",
+		"[postfix](/docs/objects#arrays-postfix)"
 	]
 }
diff --git a/ark/docs/content/docs/objects/index.mdx b/ark/docs/content/docs/objects/index.mdx
@@ -497,7 +497,7 @@ const literals = type({
 
 Constrain a Date with an inclusive or exclusive min or max.
 
-Bounds can be expressed as either a [number](/primitives#number/literals) representing its corresponding Unix epoch value or a [Date literal](/objects#dates/literals).
+Bounds can be expressed as either a [number](/docs/primitives#number-literals) representing its corresponding Unix epoch value or a [Date literal](/docs/objects#dates-literals).
 
 <SyntaxTabs>
 	<SyntaxTab string>
@@ -602,4 +602,4 @@ const instances = type({
 
 ### keywords [#instanceof-keywords]
 
-🚧 Coming soon ™️🚧
+A list of instanceof keywords can be found [here](/docs/keywords#instanceof) alongside the base and subtype keywords for [Array](/docs/keywords#array) and [FormData](/docs/keywords#formdata).
diff --git a/ark/docs/content/docs/objects/properties/meta.json b/ark/docs/content/docs/objects/properties/meta.json
@@ -1,13 +1,13 @@
 {
 	"title": "properties",
 	"pages": [
-		"[required](/docs/objects#properties/required)",
-		"[optional](/docs/objects#properties/optional)",
-		"[defaultable](/docs/objects#properties/defaultable)",
-		"[index](/docs/objects#properties/index)",
-		"[undeclared](/docs/objects#properties/undeclared)",
-		"[merge](/docs/objects#properties/merge)",
-		"[keyof](/docs/objects#properties/keyof)",
-		"[get](/docs/objects#properties/get)"
+		"[required](/docs/objects#properties-required)",
+		"[optional](/docs/objects#properties-optional)",
+		"[defaultable](/docs/objects#properties-defaultable)",
+		"[index](/docs/objects#properties-index)",
+		"[undeclared](/docs/objects#properties-undeclared)",
+		"[merge](/docs/objects#properties-merge)",
+		"[keyof](/docs/objects#properties-keyof)",
+		"[get](/docs/objects#properties-get)"
 	]
 }