upup

ark/docs/content/docs/expressions/index.mdx

@@ -141,7 +141,7 @@ const sameError = type({ a: "string.numeric.parse" }).or({ b: "string.numeric.pa
 ```
 
 <details>
-	<summary>Learn the basic set theory behind this restriction</summary>
+	<summary>Learn the set theory behind this restriction</summary>
 
 If you're relatively new to set-based types, that error might be daunting, but if you take a second to think through the example, it becomes clear why this isn't allowed. The logic of `bad` is essentially:
 
@@ -168,27 +168,37 @@ Add a type-only symbol to an existing type so that the only values that satisfy
     <SyntaxTab string>
 
 ```ts
-// hover to see ArkType's representation of a branded type
-const myObject = type({
-	brandedString: "string#id"
-})
+// @noErrors
+const even = type("(number % 2)#even")
+type Even = typeof even.infer
+
+const good: Even = even.assert(2)
+// TypeScript: Type 'number' is not assignable to type 'Brand<number, "even">'
+const bad: Even = 5
 ```
 
     </SyntaxTab>
 
     <SyntaxTab fluent>
 
 ```ts
-// hover to see ArkType's representation of a branded type
-const myObject = type({
-	brandedString: type.string.brand("id")
-})
+// @noErrors
+const even = type.number.divisibleBy(2).brand("even")
+type Even = typeof even.infer
+
+const good: Even = even.assert(2)
+// TypeScript: Type 'number' is not assignable to type 'Brand<number, "even">'
+const bad: Even = 5
 ```
 
     </SyntaxTab>
 
 </SyntaxTabs>
 
+Brands can be a great way to represent constraints that fall outside the scope TypeScript, but remember they don't change anything about what is enforced at runtime!
+
+For more information on branding in general, check out [this excellent article](https://www.learningtypescript.com/articles/branded-types) from [Josh Goldberg](https://github.com/joshuakgoldberg).
+
 ### 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).

ark/repo/scratch.ts

@@ -1,3 +1,3 @@
 import { type } from "arktype"
 
-type("string")
+const even = type.number.divisibleBy(2).brand("even")

ark/type/__tests__/brand.test.ts

@@ -70,4 +70,15 @@ contextualize(() => {
 		attest(string.json).equals(fluent.json)
 		attest<typeof fluent.t>(string.t)
 	})
+
+	it("docs example", () => {
+		const fluent = type.number.divisibleBy(2).brand("even")
+
+		attest<Brand<number, "even">>(fluent.t)
+		attest<number>(fluent.inferIn)
+		attest<Brand<number, "even">>(fluent.infer)
+
+		const string = type("(number % 2)#even")
+		attest<typeof fluent>(string).is(fluent)
+	})
 })

ark/type/__tests__/match.test.ts

@@ -1,31 +1,31 @@
-import { attest } from "@ark/attest"
-import { match } from "arktype"
-
-it("cases only", () => {
-	const sizeOf = match({
-		"string|Array": v => v.length,
-		number: v => v,
-		bigint: v => v
-	}).orThrow()
-
-	attest<number>(sizeOf("abc")).equals(3)
-	attest<number>(sizeOf([1, 2, 3])).equals(3)
-	attest<bigint>(sizeOf(5n)).equals(5n)
-})
-
-it("properly infers types of inputs/outputs", () => {
-	const matcher = match({ string: s => s, number: n => n })
-		.when("boolean", b => b)
-		.orThrow()
-
-	// properly infers the type of the output based on the input
-	attest<string>(matcher("abc")).equals("abc")
-	attest<number>(matcher(4)).equals(4)
-	attest<boolean>(matcher(true)).equals(true)
-
-	// and properly handles unions in the input type
-	attest<string | number>(matcher(0 as string | number))
-})
+// import { attest } from "@ark/attest"
+// import { match } from "arktype"
+
+// it("cases only", () => {
+// 	const sizeOf = match({
+// 		"string|Array": v => v.length,
+// 		number: v => v,
+// 		bigint: v => v
+// 	}).orThrow()
+
+// 	attest<number>(sizeOf("abc")).equals(3)
+// 	attest<number>(sizeOf([1, 2, 3])).equals(3)
+// 	attest<bigint>(sizeOf(5n)).equals(5n)
+// })
+
+// it("properly infers types of inputs/outputs", () => {
+// 	const matcher = match({ string: s => s, number: n => n })
+// 		.when("boolean", b => b)
+// 		.orThrow()
+
+// 	// properly infers the type of the output based on the input
+// 	attest<string>(matcher("abc")).equals("abc")
+// 	attest<number>(matcher(4)).equals(4)
+// 	attest<boolean>(matcher(true)).equals(true)
+
+// 	// and properly handles unions in the input type
+// 	attest<string | number>(matcher(0 as string | number))
+// })
 
 // describe('"finalizations"', () => {
 // 	it(".orThrow()", () => {

ark/type/index.ts

@@ -15,7 +15,6 @@ export {
 	define,
 	generic,
 	keywords,
-	match,
 	type,
 	type Ark
 } from "./keywords/keywords.ts"

ark/type/keywords/keywords.ts

@@ -2,7 +2,6 @@ import type { ArkErrors, arkKind } from "@ark/schema"
 import type { Brand, inferred } from "@ark/util"
 import type { distill, InferredMorph, Out, To } from "../attributes.ts"
 import type { GenericParser } from "../generic.ts"
-import type { MatchParser } from "../match.ts"
 import type { BaseType } from "../methods/base.ts"
 import type { BoundModule, Module } from "../module.ts"
 import type {
@@ -129,7 +128,7 @@ export declare namespace type {
 
 export type type<t = unknown, $ = {}> = Type<t, $>
 
-export const match: MatchParser<{}> = ark.match as never
+// export const match: MatchParser<{}> = ark.match as never
 
 export const generic: GenericParser<{}> = ark.generic as never
 

ark/type/scope.ts

@@ -52,7 +52,7 @@ import {
 	type parseValidGenericParams
 } from "./generic.ts"
 import type { Ark, type } from "./keywords/keywords.ts"
-import { InternalMatchParser, type MatchParser } from "./match.ts"
+import { InternalMatchParser } from "./match.ts"
 import type {
 	BoundModule,
 	Module,
@@ -362,7 +362,7 @@ export interface Scope<$ = {}> {
 
 	type: TypeParser<$>
 
-	match: MatchParser<$>
+	// match: MatchParser<$>
 
 	declare: DeclarationParser<$>
 

ark/util/errors.ts

@@ -1,4 +1,4 @@
-import type { keyNonimal } from "./generics.ts"
+import type { brand } from "./generics.ts"
 
 export class InternalArktypeError extends Error {}
 
@@ -48,7 +48,7 @@ export interface ErrorType<
 	message extends string = string,
 	ctx extends {} = {}
 > {
-	[keyNonimal]: "ErrorObject"
+	[brand]: "ErrorObject"
 	message: message
 	ctx: ctx
 }

ark/util/generics.ts

@@ -64,13 +64,10 @@ export type exactEquals<l, r> =
 	(<_>() => _ extends l ? 1 : 2) extends <_>() => _ extends r ? 1 : 2 ? true
 	:	false
 
-/** You can avoid suggesting completions by prefixing a string key with whitespace.
- *  Isn't that keyNominal?
- */
-export const keyNonimal = " keyNonimal"
+export const brand = noSuggest("brand")
 
 export type Brand<t = unknown, id = unknown> = t & {
-	readonly [keyNonimal]: [t, id]
+	readonly [brand]: [t, id]
 }
 
 export type unbrand<t> = t extends Brand<infer base, string> ? base : never