Add S.brand

Author: DZakh

IDEAS.md

@@ -3,6 +3,8 @@
 ## Alpha.4
 
 - Use built-in JSON String transformation for JSON String output in `S.compile`
+- Fix https://github.com/DZakh/sury/issues/150
+- Add `S.brand` for TS API
 
 ## v11
 

docs/js-usage.md

@@ -14,6 +14,7 @@
   - [JSON Schema](#json-schema)
   - [Standard Schema](#standard-schema)
 - [Defining schemas](#defining-schemas)
+  - [Advanced schemas](#advanced-schemas)
 - [Strings](#strings)
   - [ISO datetimes](#iso-datetimes)
 - [Numbers](#numbers)
@@ -368,20 +369,40 @@ S.any;
 // Never type
 // Allows no values
 S.never;
+```
+
+### Advanced schemas
+
+The goal of **Sury** is to provide the best DX. To achieve that, everything is a schema — use it directly without a `()` call. However, some schemas are opt‑in to keep bundle size small, so you must enable them explicitly. This also helps prevent your team from using the wrong API.
+
+Enable the schemas you need at the project root:
+
+```ts
+S.enableJson();
+S.enableJsonString();
+```
 
+And use them as usual:
+
+> 🧠 Don't forget `S.to` which comes with powerful coercion logic.
+
+```ts
 // JSON type
-S.enableJson(); // ❕ Call at the project root.
 // Allows string | boolean | number | null | Record<string, JSON> | JSON[]
 S.json;
 
 // JSON string
-S.enableJsonString(); // ❕ Call at the project root.
+
 // Asserts that the input is a valid JSON string
 S.jsonString;
 S.jsonStringWithSpace(2);
+
 // Parses JSON string and validates that it's a number
+// JSON string -> number
 S.jsonString.with(S.to, S.number);
+
 // Serializes number to JSON string
+// number -> JSON string
 S.number.with(S.to, S.jsonString);
 ```
 
@@ -867,6 +888,41 @@ S.toJSONSchema(documentedStringSchema);
 // }
 ```
 
+## Brand
+
+Add a type-only symbol to an existing type so that only values produced by validation satisfy it.
+
+Use `S.brand` to attach a nominal brand to a schema's output. This is a TypeScript-only marker: it does not change runtime behavior. Combine it with `S.refine` (or any validation) so only validated values can acquire the brand.
+
+```ts
+// Brand a string as a UserId
+const UserId = S.string.with(S.brand, "UserId");
+type UserId = S.Infer<typeof UserId>; // S.Brand<string, "UserId">
+
+const id: UserId = S.parseOrThrow("u_123", UserId); // OK
+const asString: string = id; // OK: branded value is assignable to string
+// @ts-expect-error - A plain string is not assignable to a branded string
+const notId: UserId = "u_123";
+```
+
+You can define brands for refined constraints, like even numbers:
+
+```ts
+const even = S.number
+  .with(S.refine, (value, s) => {
+    if (value % 2 !== 0) s.fail("Expected an even number");
+  })
+  .with(S.brand, "even");
+
+type Even = S.Infer<typeof even>; // S.Brand<number, "even">
+
+const good: Even = S.parseOrThrow(2, even); // OK
+// @ts-expect-error - number is not assignable to brand "even"
+const bad: Even = 5;
+```
+
+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).
+
 ## Custom schema
 
 **Sury** might not have many built-in schemas for your use case. In this case you can create a custom schema for any TypeScript type.

packages/sury/scripts/pack/Pack.res

@@ -182,6 +182,7 @@ let filesMapping = [
   ("enableJson", "S.enableJson"),
   ("enableJsonString", "S.enableJsonString"),
   ("global", "S.global"),
+  ("brand", "s => s"),
 ]
 
 sourePaths->Array.forEach(path => {

packages/sury/scripts/pack/Pack.res.mjs

@@ -332,6 +332,10 @@ let filesMapping = [
   [
     "global",
     "S.global"
+  ],
+  [
+    "brand",
+    "s => s"
   ]
 ];
 

packages/sury/src/S.d.ts

@@ -118,6 +118,10 @@ export type Schema<Output, Input = unknown> = {
   ): Schema<Output, Input>;
   // with(message: string): t<Output, Input>; TODO: implement
   with<O, I>(fn: (schema: Schema<Output, Input>) => Schema<O, I>): Schema<O, I>;
+  with<O, I, A1 extends string>(
+    fn: (schema: Schema<Output, Input>, arg1: A1) => Schema<O, I>,
+    arg1: A1
+  ): Schema<O, I>;
   with<O, I, A1>(
     fn: (schema: Schema<Output, Input>, arg1: A1) => Schema<O, I>,
     arg1: A1
@@ -298,6 +302,19 @@ export type UnknownToInput<T> = T extends Schema<unknown, infer Input>
     >
   : T;
 
+export type Brand<T, ID extends string> = T & {
+  /**
+   *  TypeScript won't suggest strings beginning with a space as properties.
+   *  Useful for symbol-like string properties.
+   */
+  readonly [" brand"]: [T, ID];
+};
+
+export function brand<ID extends string, Output = unknown, Input = unknown>(
+  schema: Schema<Output, Input>,
+  brandId: ID
+): Schema<Brand<Output, ID>, Input>;
+
 // Grok told that it makes things faster
 // TODO: Verify it with ArkType test framework
 type HasUndefined<T> = [T] extends [undefined]

packages/sury/src/S.js

@@ -70,4 +70,5 @@ export var datetime = S.datetime
 export var trim = S.trim
 export var enableJson = S.enableJson
 export var enableJsonString = S.enableJsonString
-export var global = S.global
+export var global = S.global
+export var brand = s => s

packages/sury/tests/S_test.ts

@@ -2600,6 +2600,18 @@ test("Example of transformed schema", (t) => {
   }
 });
 
+test("Brand", (t) => {
+  const schema = S.string.with(S.brand, "Foo");
+  type Foo = S.Infer<typeof schema>;
+  expectType<SchemaEqual<typeof schema, S.Brand<string, "Foo">, string>>(true);
+  const result = S.parseOrThrow("hello", schema);
+  expectType<S.Brand<string, "Foo">>(result);
+  t.deepEqual(result, "hello");
+
+  // @ts-expect-error - Branded string is not assignable to string
+  const a: Foo = "bar";
+});
+
 test("fromJSONSchema", (t) => {
   const emailSchema = S.fromJSONSchema<string>({
     type: "string",