@kizunajs/fetch 2.0.0-beta.12 → 2.0.0-beta.13

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { $brand, z } from "zod";
 import { AUTO_GUARD_BRAND, AUTO_RESPONSES_BRAND, ExtractPathParams, HasPathParams, Method, ProblemDetails, RequestContextHeaderInputs, RouteDefinition, RoutePath, Routes, StreamMessageOf, StreamResponseDefinition, ValidationError, ValidationError as ValidationError$1, ValidationErrorFor, isProblemDetails, isValidationError } from "kizunajs";
 
 //#region src/client.d.ts
@@ -163,4 +163,4 @@ interface GeneratedRoutes {
  */
 declare const createGeneratedClient: (routes: GeneratedRoutes, config: ClientConfig) => Record<string, unknown>;
 //#endregion
-export { CLIENT_ROUTE, Client, ClientArgs, ClientConfig, ClientMethod, ClientResponse, ContextHeaderInputs, GeneratedResponse, GeneratedRoute, GeneratedRoutes, OutgoingRequest, type ValidationError, createGeneratedClient, isProblemDetails, isValidationError, routeOf };
+export { type $brand, CLIENT_ROUTE, Client, ClientArgs, ClientConfig, ClientMethod, ClientResponse, ContextHeaderInputs, GeneratedResponse, GeneratedRoute, GeneratedRoutes, OutgoingRequest, type ValidationError, createGeneratedClient, isProblemDetails, isValidationError, routeOf };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { AUTO_GUARD_BRAND, AUTO_RESPONSES_BRAND, ExtractPathParams, HasPathParams, Method, ProblemDetails, RequestContextHeaderInputs, RouteDefinition, RoutePath, Routes, StreamMessageOf, StreamResponseDefinition, ValidationError, ValidationError as ValidationError$1, ValidationErrorFor, isProblemDetails, isValidationError } from "kizunajs";
-import { z } from "zod";
+import { $brand, z } from "zod";
 
 //#region src/client.d.ts
 type ResponseUnion<R extends RouteDefinition> = { [S in keyof R['responses']]: {
@@ -163,4 +163,4 @@ interface GeneratedRoutes {
  */
 declare const createGeneratedClient: (routes: GeneratedRoutes, config: ClientConfig) => Record<string, unknown>;
 //#endregion
-export { CLIENT_ROUTE, Client, ClientArgs, ClientConfig, ClientMethod, ClientResponse, ContextHeaderInputs, GeneratedResponse, GeneratedRoute, GeneratedRoutes, OutgoingRequest, type ValidationError, createGeneratedClient, isProblemDetails, isValidationError, routeOf };
+export { type $brand, CLIENT_ROUTE, Client, ClientArgs, ClientConfig, ClientMethod, ClientResponse, ContextHeaderInputs, GeneratedResponse, GeneratedRoute, GeneratedRoutes, OutgoingRequest, type ValidationError, createGeneratedClient, isProblemDetails, isValidationError, routeOf };

package/dist/server.cjs

@@ -10,6 +10,7 @@ let zod = require("zod");
 var TypeCollector = class {
 	named = /* @__PURE__ */ new Map();
 	claimed = /* @__PURE__ */ new Set();
+	brands = /* @__PURE__ */ new Map();
 	/**
 	* Claims a name before its body is walked, so a model that refers to itself
 	* resolves to its own name instead of recursing. Answers whether the caller
@@ -23,12 +24,55 @@ var TypeCollector = class {
 	add(type) {
 		this.named.set(type.name, type);
 	}
+	/**
+	* Declares a brand as a named type, `UserId = string & $brand<"UserId">`,
+	* and answers the name.
+	*/
+	addBrand(brand, base, example) {
+		const name = (0, kizunajs_generator.sanitizeIdentifier)(brand);
+		const existing = this.brands.get(name);
+		if (existing !== void 0 && (existing.brand !== brand || existing.base !== base)) throw new Error(`@kizunajs/fetch: brand ${quote(brand)} wraps both ${existing.base} and ${base}. Give each its own name.`);
+		if (existing === void 0) this.brands.set(name, {
+			brand,
+			base,
+			example
+		});
+		return name;
+	}
+	usesBrand() {
+		return this.brands.size > 0;
+	}
+	/**
+	* Each brand's name, the type it wraps, and a value for its `@example`, for
+	* the constructors the file exports.
+	*/
+	allBrands() {
+		return [...this.brands].map(([name, { base, example }]) => ({
+			name,
+			base,
+			example
+		}));
+	}
 	all() {
-		return [...this.named.values()].sort((left, right) => left.name.localeCompare(right.name));
+		for (const name of this.brands.keys()) if (this.named.has(name)) throw new Error(`@kizunajs/fetch: brand ${quote(name)} has the same name as a model. Give each its own name.`);
+		const brands = [...this.brands].map(([name, { brand, base }]) => ({
+			name,
+			description: `A branded \`${base}\`. Responses hand one back, and \`to${name}\` makes one from a plain value.`,
+			body: `${base} & $brand<${quote(brand)}>`
+		}));
+		return [...this.named.values(), ...brands].sort((left, right) => left.name.localeCompare(right.name));
 	}
 };
 const quote = (value) => JSON.stringify(value);
 /**
+* What a brand wraps: the scalars, as the JSON carries them.
+*/
+const BRANDABLE_BASES = new Set([
+	"string",
+	"number",
+	"boolean"
+]);
+/**
 * A literal as the type the JSON carries, so `z.literal(true)` is `true`.
 */
 const literalType = (value) => {
@@ -161,9 +205,15 @@ const objectBody = (schema, collector, hint) => {
 };
 /**
 * The TypeScript type a schema describes. Named models are collected and
-* referenced; anonymous shapes are inlined.
+* referenced; anonymous shapes are inlined. A brand is named like a model.
 */
 const typeOf = (schema, collector, hint) => {
+	const type = unbrandedTypeOf(schema, collector, hint);
+	const brand = (0, kizunajs_generator.readMetaBrand)(schema);
+	if (brand === void 0 || !BRANDABLE_BASES.has(type)) return type;
+	return collector.addBrand(brand, type, sampleValue(schema, 0, brand));
+};
+const unbrandedTypeOf = (schema, collector, hint) => {
 	if ((0, kizunajs_generator.isFileSchema)(schema)) return "File | Blob";
 	if ((0, kizunajs_generator.isBinarySchema)(schema)) return "Uint8Array";
 	const def = (0, kizunajs_generator.readDef)(schema);
@@ -388,14 +438,27 @@ const emitRequestContext = (contract, collector) => {
 	}
 	return fields.length > 0 ? `export interface RequestContext {\n${indent(fields.join("\n"))}\n}` : void 0;
 };
+/**
+* A constructor per brand, so a value from outside the API becomes one with
+* `toUserId('usr_k7f3q9')` rather than a cast.
+*/
+const emitBrandConstructors = (collector, namespaceName) => collector.allBrands().map(({ name, base, example }) => `
+${docComment([
+	`Brands a value from outside the API, like a URL segment, as \`${namespaceName}.${name}\`. A value from a response is branded already.`,
+	"",
+	"@example",
+	`const id = to${name}(${example});`
+])}export const to${name} = (value: ${base}): ${namespaceName}.${name} => value as ${namespaceName}.${name};
+`).join("");
 const generateFetchClient = (contract, options = {}) => {
 	const { namespace: namespaceName = "API", runtimeModule = "@kizunajs/fetch", regenerateCommand = "kizuna generate", source } = options;
 	const collector = new TypeCollector();
 	const tree = emitTree((0, kizunajs_generator.listedRoutes)(contract), "", collector, namespaceName);
+	const requestContext = emitRequestContext(contract, collector);
 	const api = [...collector.all().map((model) => {
 		return `${model.description ? `/**\n * ${model.description}\n */\n` : ""}export type ${model.name} = ${model.body};`;
 	}), ...tree.declarations].join("\n\n");
-	const requestContext = emitRequestContext(contract, collector);
+	const brands = emitBrandConstructors(collector, namespaceName);
 	return `/* eslint-disable */
 /**
 ${[
@@ -405,7 +468,7 @@ ${[
 		` * Regenerate: ${regenerateCommand}`
 	].join("\n")}
  */
-import { createGeneratedClient, type ClientConfig, type ClientMethod, type GeneratedRoutes } from '${runtimeModule}';
+import { createGeneratedClient, ${collector.usesBrand() ? "type $brand, " : ""}type ClientConfig, type ClientMethod, type GeneratedRoutes } from '${runtimeModule}';
 
 export namespace ${namespaceName} {
 ${indent(api)}
@@ -418,7 +481,7 @@ ${indent(tree.signatures)}
 const routes: GeneratedRoutes = {
 ${indent(tree.table)}
 };
-
+${brands}
 ${requestContext === void 0 ? `/**
  * A client for this API. Pass the base URL and anything else the runtime takes.
  */

package/dist/server.mjs

@@ -1,5 +1,5 @@
 import { ValidationErrorSchema } from "kizunajs/schemas";
-import { defineClient, isBinarySchema, isFileSchema, isStreamResponse, isVoidSchema, listedRoutes, readDef, readDeprecation, readDiscriminatedUnion, readMetaDescription, readMetaExamples, readMetaId, readObjectShape, resolveResponseBody, resolveResponseHeaders, streamContentType, toPascalCase, unwrapOptionalWrappers } from "kizunajs/generator";
+import { defineClient, isBinarySchema, isFileSchema, isStreamResponse, isVoidSchema, listedRoutes, readDef, readDeprecation, readDiscriminatedUnion, readMetaBrand, readMetaDescription, readMetaExamples, readMetaId, readObjectShape, resolveResponseBody, resolveResponseHeaders, sanitizeIdentifier, streamContentType, toPascalCase, unwrapOptionalWrappers } from "kizunajs/generator";
 import { z } from "zod";
 //#region src/zod-to-typescript.ts
 /**
@@ -9,6 +9,7 @@ import { z } from "zod";
 var TypeCollector = class {
 	named = /* @__PURE__ */ new Map();
 	claimed = /* @__PURE__ */ new Set();
+	brands = /* @__PURE__ */ new Map();
 	/**
 	* Claims a name before its body is walked, so a model that refers to itself
 	* resolves to its own name instead of recursing. Answers whether the caller
@@ -22,12 +23,55 @@ var TypeCollector = class {
 	add(type) {
 		this.named.set(type.name, type);
 	}
+	/**
+	* Declares a brand as a named type, `UserId = string & $brand<"UserId">`,
+	* and answers the name.
+	*/
+	addBrand(brand, base, example) {
+		const name = sanitizeIdentifier(brand);
+		const existing = this.brands.get(name);
+		if (existing !== void 0 && (existing.brand !== brand || existing.base !== base)) throw new Error(`@kizunajs/fetch: brand ${quote(brand)} wraps both ${existing.base} and ${base}. Give each its own name.`);
+		if (existing === void 0) this.brands.set(name, {
+			brand,
+			base,
+			example
+		});
+		return name;
+	}
+	usesBrand() {
+		return this.brands.size > 0;
+	}
+	/**
+	* Each brand's name, the type it wraps, and a value for its `@example`, for
+	* the constructors the file exports.
+	*/
+	allBrands() {
+		return [...this.brands].map(([name, { base, example }]) => ({
+			name,
+			base,
+			example
+		}));
+	}
 	all() {
-		return [...this.named.values()].sort((left, right) => left.name.localeCompare(right.name));
+		for (const name of this.brands.keys()) if (this.named.has(name)) throw new Error(`@kizunajs/fetch: brand ${quote(name)} has the same name as a model. Give each its own name.`);
+		const brands = [...this.brands].map(([name, { brand, base }]) => ({
+			name,
+			description: `A branded \`${base}\`. Responses hand one back, and \`to${name}\` makes one from a plain value.`,
+			body: `${base} & $brand<${quote(brand)}>`
+		}));
+		return [...this.named.values(), ...brands].sort((left, right) => left.name.localeCompare(right.name));
 	}
 };
 const quote = (value) => JSON.stringify(value);
 /**
+* What a brand wraps: the scalars, as the JSON carries them.
+*/
+const BRANDABLE_BASES = new Set([
+	"string",
+	"number",
+	"boolean"
+]);
+/**
 * A literal as the type the JSON carries, so `z.literal(true)` is `true`.
 */
 const literalType = (value) => {
@@ -160,9 +204,15 @@ const objectBody = (schema, collector, hint) => {
 };
 /**
 * The TypeScript type a schema describes. Named models are collected and
-* referenced; anonymous shapes are inlined.
+* referenced; anonymous shapes are inlined. A brand is named like a model.
 */
 const typeOf = (schema, collector, hint) => {
+	const type = unbrandedTypeOf(schema, collector, hint);
+	const brand = readMetaBrand(schema);
+	if (brand === void 0 || !BRANDABLE_BASES.has(type)) return type;
+	return collector.addBrand(brand, type, sampleValue(schema, 0, brand));
+};
+const unbrandedTypeOf = (schema, collector, hint) => {
 	if (isFileSchema(schema)) return "File | Blob";
 	if (isBinarySchema(schema)) return "Uint8Array";
 	const def = readDef(schema);
@@ -387,14 +437,27 @@ const emitRequestContext = (contract, collector) => {
 	}
 	return fields.length > 0 ? `export interface RequestContext {\n${indent(fields.join("\n"))}\n}` : void 0;
 };
+/**
+* A constructor per brand, so a value from outside the API becomes one with
+* `toUserId('usr_k7f3q9')` rather than a cast.
+*/
+const emitBrandConstructors = (collector, namespaceName) => collector.allBrands().map(({ name, base, example }) => `
+${docComment([
+	`Brands a value from outside the API, like a URL segment, as \`${namespaceName}.${name}\`. A value from a response is branded already.`,
+	"",
+	"@example",
+	`const id = to${name}(${example});`
+])}export const to${name} = (value: ${base}): ${namespaceName}.${name} => value as ${namespaceName}.${name};
+`).join("");
 const generateFetchClient = (contract, options = {}) => {
 	const { namespace: namespaceName = "API", runtimeModule = "@kizunajs/fetch", regenerateCommand = "kizuna generate", source } = options;
 	const collector = new TypeCollector();
 	const tree = emitTree(listedRoutes(contract), "", collector, namespaceName);
+	const requestContext = emitRequestContext(contract, collector);
 	const api = [...collector.all().map((model) => {
 		return `${model.description ? `/**\n * ${model.description}\n */\n` : ""}export type ${model.name} = ${model.body};`;
 	}), ...tree.declarations].join("\n\n");
-	const requestContext = emitRequestContext(contract, collector);
+	const brands = emitBrandConstructors(collector, namespaceName);
 	return `/* eslint-disable */
 /**
 ${[
@@ -404,7 +467,7 @@ ${[
 		` * Regenerate: ${regenerateCommand}`
 	].join("\n")}
  */
-import { createGeneratedClient, type ClientConfig, type ClientMethod, type GeneratedRoutes } from '${runtimeModule}';
+import { createGeneratedClient, ${collector.usesBrand() ? "type $brand, " : ""}type ClientConfig, type ClientMethod, type GeneratedRoutes } from '${runtimeModule}';
 
 export namespace ${namespaceName} {
 ${indent(api)}
@@ -417,7 +480,7 @@ ${indent(tree.signatures)}
 const routes: GeneratedRoutes = {
 ${indent(tree.table)}
 };
-
+${brands}
 ${requestContext === void 0 ? `/**
  * A client for this API. Pass the base URL and anything else the runtime takes.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kizunajs/fetch",
-  "version": "2.0.0-beta.12",
+  "version": "2.0.0-beta.13",
   "description": "Typed fetch client for Kizuna.js APIs",
   "keywords": [
     "kizunajs",
@@ -68,7 +68,7 @@
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "kizunajs": "2.0.0-beta.12"
+    "kizunajs": "2.0.0-beta.13"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
@@ -76,8 +76,8 @@
     "tsdown": "^0.21.0",
     "typescript": "^6.0.3",
     "zod": "^4.0.0",
-    "kizunajs": "2.0.0-beta.12",
-    "@kizunajs/express": "2.0.0-beta.12"
+    "kizunajs": "2.0.0-beta.13",
+    "@kizunajs/express": "2.0.0-beta.13"
   },
   "scripts": {
     "build": "tsdown src/index.ts src/server.ts --format esm,cjs --dts --clean --external kizunajs --external zod",