@jfdevelops/create-error 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joey F.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,294 @@
+# @jfdevelops/create-error
+
+Create strongly typed, configurable error families from any synchronous
+[Standard Schema](https://standardschema.dev/schema) object.
+
+## Install
+
+```sh
+pnpm add @jfdevelops/create-error
+```
+
+Bring your own Standard Schema-compatible validation library, such as Zod,
+Valibot, or ArkType. `create-error` does not bundle one.
+
+## Quick start
+
+```ts
+import { createError } from '@jfdevelops/create-error';
+import { z } from 'zod';
+
+const createFormError = createError({
+  definition: z.object({
+    code: z.string(),
+    scope: z.string(),
+  }),
+  data: {
+    property: 'context',
+    resolve({ definition, input }) {
+      return { ...input, scope: definition.scope };
+    },
+  },
+  message({ definition, data, implementation }) {
+    return implementation({
+      context: data,
+      scope: definition.scope,
+    });
+  },
+  properties({ definition, data, implementation }) {
+    return {
+      code: definition.code,
+      scope: definition.scope,
+      context: data,
+      renderMessage(renderer = implementation) {
+        return renderer({
+          context: data,
+          scope: definition.scope,
+        });
+      },
+    };
+  },
+  toJSON(error) {
+    return {
+      name: error.name,
+      code: error.code,
+      scope: error.scope,
+      message: error.message,
+      context: error.context,
+    };
+  },
+});
+
+export const FormError = createFormError.Error;
+
+export class InvalidFieldError extends createFormError({
+  code: 'invalidField',
+  scope: 'field',
+})
+  .defineContext(
+    z.object({
+      field: z.string(),
+      scope: z.literal('field'),
+    }),
+  )
+  .implement(
+    ({ code, context }) => `${code}: ${context.field} is invalid`,
+  ) {}
+
+const error = new InvalidFieldError({ field: 'email' });
+
+error.code; // "invalidField"
+error.scope; // "field"
+error.context; // { field: string; scope: "field" }
+error instanceof Error; // true
+error instanceof FormError; // true
+```
+
+No explicit generic arguments or `as const` assertions are needed. Definition
+inputs are checked by the schema, and definition-derived fields use its parsed
+output type so transformations remain type-safe.
+
+For reusable or separately declared configurations, the package exports a
+common `CreateErrorConfig` type:
+
+```ts
+import { createError, type CreateErrorConfig } from '@jfdevelops/create-error';
+
+const definition = z.object({ code: z.string() });
+
+const config = {
+  definition,
+  data: {
+    property: 'context',
+    resolve: ({ input }) => input,
+  },
+  message: ({ data, implementation }) => implementation(data),
+} satisfies CreateErrorConfig<typeof definition>;
+
+const createDomainError = createError(config);
+```
+
+## How the factory works
+
+The API has four stages:
+
+1. `createError(blueprint)` configures a family and returns a factory.
+2. `factory(definition)` validates and captures one definition.
+3. The returned builder optionally selects a context schema with
+   `defineContext(schema)`.
+4. `implement(callback)` captures the implementation and produces an
+   extendable concrete error class.
+
+The definition builder exposes both `defineContext` and `implement`.
+`defineContext` returns a narrower builder that exposes only `implement`, so a
+context schema can be selected only once. Calling `implement` directly keeps
+context schemas optional. Every implementation receives exactly one argument;
+the blueprint decides its shape when it calls `implementation(argument)`. When
+that argument is a constructed object, the concrete definition fields are added
+automatically, so implementations can read values such as `code` without the
+blueprint repeating them. Forwarding opaque data directly preserves its original
+scalar, tuple, object, or class-instance shape.
+
+The `definition` option must implement Standard Schema V1 and must produce an
+object. Validation runs when `factory(definition)` is called. Because class
+creation is synchronous, a schema whose `validate` method returns a promise is
+rejected with a `TypeError`.
+
+## What `data` and `properties` do
+
+`data` defines the constructor-input lifecycle. Its `resolve` callback receives
+the concrete definition and the value passed to `new ErrorClass(input)`. The
+callback can preserve that input, normalize it, or combine it with definition
+values. After optional `defineContext` validation, the final value is stored on
+the instance using `data.property`.
+
+`properties` defines the rest of the instance API. It can expose definition
+values such as a stable error code, derive fields from the resolved data, or add
+methods and getters. It does not participate in input validation or
+transformation.
+
+For a small error family, the constructor input can pass straight through and
+`properties` can be omitted entirely:
+
+```ts
+const createLookupError = createError({
+  definition: z.object({ code: z.string() }),
+  data: {
+    property: 'resourceId',
+    resolve: ({ input }) => input,
+  },
+  message: ({ data, implementation }) => implementation(data),
+});
+
+class MissingUserError extends createLookupError({ code: 'missingUser' })
+  .defineContext(z.string())
+  .implement((resourceId) => `User ${resourceId} was not found`) {}
+
+const error = new MissingUserError('user_123');
+error.resourceId; // string
+```
+
+Use both options when constructor input needs normalization and the error should
+present a richer public API:
+
+```ts
+const createValidationError = createError({
+  definition: z.object({
+    code: z.string(),
+    section: z.string(),
+  }),
+  data: {
+    property: 'context',
+    resolve: ({ definition, input }) => ({
+      ...input,
+      section: definition.section,
+    }),
+  },
+  message: ({ data, implementation }) => implementation(data),
+  properties: ({ definition, data }) => ({
+    code: definition.code,
+    section: definition.section,
+    describe: () => `${definition.code} in ${data.section}`,
+  }),
+});
+
+class InvalidEmailError extends createValidationError({
+  code: 'invalidEmail',
+  section: 'profile',
+})
+  .defineContext(
+    z.object({
+      field: z.string(),
+      section: z.literal('profile'),
+    }),
+  )
+  .implement(({ field }) => `${field} is invalid`) {}
+
+const error = new InvalidEmailError({ field: 'email' });
+error.context; // { field: string; section: "profile" }
+error.code; // "invalidEmail"
+error.describe(); // "invalidEmail in profile"
+```
+
+Use schema-native restrictions when definitions have a closed set of values:
+
+```ts
+const createHttpError = createError({
+  definition: z.object({
+    code: z.enum(['notFound', 'unauthorized']),
+    scope: z.literal('request'),
+  }),
+  data: {
+    property: 'details',
+    resolve: ({ input }) => input,
+  },
+  message: ({ implementation, data }) => implementation(data),
+});
+
+const NotFoundError = createHttpError({
+  code: 'notFound',
+  scope: 'request',
+})
+  .defineContext(z.object({ resource: z.string() }))
+  .implement((details) => `${details.resource} was not found`);
+```
+
+## Data and behavior
+
+`data.resolve` can return any value: objects, scalars, tuples, unions, class
+instances, `null`, and `undefined` are all supported. When `defineContext` is
+used, its Standard Schema validates the resolved data, its input type determines
+the concrete error constructor input, and its output type is passed to the
+implementation and stored on the error. Without a context schema, the last
+parameter of the consumer implementation determines those types.
+
+For each new error instance, callbacks run in this order:
+
+1. `data.resolve`
+2. Context validation and transformation, when configured
+3. `message`
+4. `properties`, when configured
+
+Exceptions thrown by a schema or callback are not wrapped. Native `Error`
+behavior is preserved, including stack traces, subclass names, prototypes, and
+the optional `cause` passed as the second constructor argument.
+
+Every family exposes its shared base as `factory.Error`. Concrete classes and
+named subclasses also inherit a lazy invariant helper:
+
+```ts
+InvalidFieldError.invariant(
+  formIsValid,
+  () => ({ field: 'email' }),
+  { cause },
+);
+```
+
+The input function runs only when the condition is falsy.
+
+When `toJSON` is configured, it is installed once on the family prototype and
+used by `JSON.stringify`. Its callback can read native error fields, configured
+properties, and the resolved data property; each concrete error's `toJSON()`
+return type preserves parsed definition output and context-schema output. When
+omitted, the family does not add a `toJSON` method.
+
+## Property safety
+
+`properties` may add fields, methods, getters, symbols, and other own property
+descriptors. It cannot replace `name`, `message`, `stack`, `cause`,
+`constructor`, or `prototype`. The configured data property may only be
+repeated with the exact resolved value. Collisions throw a `TypeError`.
+
+The library always creates the family base class. Customize a family through
+the blueprint instead of supplying a separate `BaseError`.
+
+## Releasing
+
+This project uses Changesets for versioning and changelogs. Add a changeset
+with `pnpm changeset` whenever a package change should be released. Maintainers
+can consume pending changesets with `pnpm version-packages`, review the updated
+version and changelog, then publish with `pnpm release`.
+
+## License
+
+MIT

package/dist/create-error.cjs

@@ -0,0 +1,135 @@
+
+//#region src/create-error.ts
+const protectedPropertyNames = new Set([
+	"name",
+	"message",
+	"stack",
+	"cause",
+	"constructor",
+	"prototype"
+]);
+function isObjectLike(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function");
+}
+function isPlainObject(value) {
+	if (!isObjectLike(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function includeDefinition(argument, definition) {
+	if (!isPlainObject(argument)) return argument;
+	return {
+		...definition,
+		...argument
+	};
+}
+function validateStandardSchema(schema, subject) {
+	if (!isObjectLike(schema)) throw new TypeError(`${subject} must be a Standard Schema object`);
+	const standard = Reflect.get(schema, "~standard");
+	if (!isObjectLike(standard) || Reflect.get(standard, "version") !== 1 || typeof Reflect.get(standard, "vendor") !== "string" || typeof Reflect.get(standard, "validate") !== "function") throw new TypeError(`${subject} must implement Standard Schema V1`);
+}
+function validateBlueprint(config) {
+	validateStandardSchema(config.definition, "definition");
+	if (typeof config.data.property !== "string" || config.data.property.length === 0) throw new TypeError("data.property must be a non-empty string");
+	if (protectedPropertyNames.has(config.data.property)) throw new TypeError(`data.property cannot overwrite protected property "${config.data.property}"`);
+}
+function formatIssuePath(path) {
+	if (!path?.length) return "";
+	return `${path.map((segment) => typeof segment === "object" ? segment.key : segment).map(String).join(".")}: `;
+}
+function parseSchema(schema, input, subject) {
+	const result = schema["~standard"].validate(input);
+	if (result instanceof Promise) throw new TypeError(`${subject} schema validation must be synchronous`);
+	if (result.issues) {
+		const details = result.issues.map((issue) => `${formatIssuePath(issue.path)}${issue.message}`).join("; ");
+		throw new TypeError(`Invalid error ${subject}: ${details}`);
+	}
+	return result.value;
+}
+function parseDefinition(schema, definition) {
+	const parsedDefinition = parseSchema(schema, definition, "definition");
+	if (!isObjectLike(parsedDefinition)) throw new TypeError("definition schema must produce an object");
+	return parsedDefinition;
+}
+function assignProperties(error, properties, dataProperty, data) {
+	for (const key of Reflect.ownKeys(properties)) {
+		if (typeof key === "string" && protectedPropertyNames.has(key)) throw new TypeError(`Cannot overwrite protected error property "${key}"`);
+		const descriptor = Object.getOwnPropertyDescriptor(properties, key);
+		if (!descriptor) continue;
+		if (key === dataProperty && (!("value" in descriptor) || descriptor.value !== data)) throw new TypeError(`Cannot overwrite resolved data property "${dataProperty}"`);
+		Object.defineProperty(error, key, descriptor);
+	}
+}
+function createError(config) {
+	validateBlueprint(config);
+	class FamilyError extends Error {
+		static invariant(condition, input, options) {
+			if (condition) return;
+			const resolvedInput = typeof input === "function" ? input() : input;
+			throw new this(resolvedInput, options);
+		}
+		constructor(message, options) {
+			super(message, options);
+			const name = new.target.name;
+			if (name) this.name = name;
+		}
+	}
+	if (config.toJSON) Object.defineProperty(FamilyError.prototype, "toJSON", {
+		configurable: true,
+		value: function toJSON() {
+			return config.toJSON?.(this);
+		},
+		writable: true
+	});
+	function createDefinition(definition) {
+		const parsedDefinition = parseDefinition(config.definition, definition);
+		function createImplementation(implementation, contextSchema) {
+			return class extends FamilyError {
+				constructor(input, options) {
+					const resolvedData = config.data.resolve({
+						definition: parsedDefinition,
+						input
+					});
+					const data = contextSchema ? parseSchema(contextSchema, resolvedData, "context") : resolvedData;
+					const implementationWithDefinition = (argument) => implementation(argument === data ? argument : includeDefinition(argument, parsedDefinition));
+					const message = config.message({
+						data,
+						definition: parsedDefinition,
+						implementation: implementationWithDefinition
+					});
+					super(message, options);
+					Object.defineProperty(this, config.data.property, {
+						configurable: true,
+						enumerable: true,
+						value: data,
+						writable: true
+					});
+					const properties = config.properties?.({
+						data,
+						definition: parsedDefinition,
+						implementation: implementationWithDefinition
+					});
+					if (properties) assignProperties(this, properties, config.data.property, data);
+				}
+			};
+		}
+		function implement(implementation) {
+			return createImplementation(implementation);
+		}
+		function defineContext(contextSchema) {
+			validateStandardSchema(contextSchema, "context");
+			return { implement(implementation) {
+				return createImplementation(implementation, contextSchema);
+			} };
+		}
+		return {
+			defineContext,
+			implement
+		};
+	}
+	return Object.assign(createDefinition, { Error: FamilyError });
+}
+
+//#endregion
+exports.createError = createError;
+//# sourceMappingURL=create-error.cjs.map

package/dist/create-error.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-error.cjs","names":["implementationWithDefinition: RuntimeImplementation"],"sources":["../src/create-error.ts"],"sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec';\r\n\r\nimport type {\r\n  BlueprintContext,\r\n  BlueprintErrorTemplate,\r\n  CreateErrorConfig,\r\n  ErrorFamilyFactory,\r\n} from './types.js';\r\n\r\ntype RuntimeImplementation = (argument: unknown) => string;\r\n\r\ntype ErrorConfigBody<\r\n  Schema extends StandardSchemaV1,\r\n  DataConfig extends CreateErrorConfig<Schema>['data'],\r\n  MessageCallback extends CreateErrorConfig<Schema>['message'],\r\n> = {\r\n  data: DataConfig;\r\n  message: MessageCallback;\r\n};\r\n\r\ntype ErrorConfigWithProperties<\r\n  Schema extends StandardSchemaV1,\r\n  DataConfig extends CreateErrorConfig<Schema>['data'],\r\n  MessageCallback extends CreateErrorConfig<Schema>['message'],\r\n  Properties extends object,\r\n> = ErrorConfigBody<Schema, DataConfig, MessageCallback> & {\r\n  properties(context: BlueprintContext<Schema>): Properties;\r\n};\r\n\r\ntype ErrorConfigWithoutProperties<\r\n  Schema extends StandardSchemaV1,\r\n  DataConfig extends CreateErrorConfig<Schema>['data'],\r\n  MessageCallback extends CreateErrorConfig<Schema>['message'],\r\n> = ErrorConfigBody<Schema, DataConfig, MessageCallback> & {\r\n  properties?: never;\r\n};\r\n\r\ntype ExactCreateErrorConfig<\r\n  Schema extends StandardSchemaV1,\r\n  Config extends object,\r\n> = {\r\n  definition: Schema;\r\n} & Config &\r\n  (StandardSchemaV1.InferOutput<Schema> extends object\r\n    ? unknown\r\n    : { definition: never });\r\n\r\ntype SerializedCreateErrorConfig<\r\n  Schema extends StandardSchemaV1,\r\n  Config extends object,\r\n  Json,\r\n> = ExactCreateErrorConfig<\r\n  Schema,\r\n  Config & {\r\n    toJSON(error: BlueprintErrorTemplate<NoInfer<Config>>): Json;\r\n  }\r\n>;\r\n\r\nconst protectedPropertyNames = new Set([\r\n  'name',\r\n  'message',\r\n  'stack',\r\n  'cause',\r\n  'constructor',\r\n  'prototype',\r\n]);\r\n\r\nfunction isObjectLike(value: unknown): value is object {\r\n  return (\r\n    value !== null && (typeof value === 'object' || typeof value === 'function')\r\n  );\r\n}\r\n\r\nfunction isPlainObject(value: unknown): value is Record<PropertyKey, unknown> {\r\n  if (!isObjectLike(value)) {\r\n    return false;\r\n  }\r\n\r\n  const prototype = Object.getPrototypeOf(value);\r\n\r\n  return prototype === Object.prototype || prototype === null;\r\n}\r\n\r\nfunction includeDefinition(\r\n  argument: unknown,\r\n  definition: object,\r\n): unknown {\r\n  if (!isPlainObject(argument)) {\r\n    return argument;\r\n  }\r\n\r\n  return { ...definition, ...argument };\r\n}\r\n\r\nfunction validateStandardSchema(schema: unknown, subject: string) {\r\n  if (!isObjectLike(schema)) {\r\n    throw new TypeError(`${subject} must be a Standard Schema object`);\r\n  }\r\n\r\n  const standard = Reflect.get(schema, '~standard') as unknown;\r\n\r\n  if (\r\n    !isObjectLike(standard) ||\r\n    Reflect.get(standard, 'version') !== 1 ||\r\n    typeof Reflect.get(standard, 'vendor') !== 'string' ||\r\n    typeof Reflect.get(standard, 'validate') !== 'function'\r\n  ) {\r\n    throw new TypeError(`${subject} must implement Standard Schema V1`);\r\n  }\r\n}\r\n\r\nfunction validateBlueprint(config: CreateErrorConfig<StandardSchemaV1>) {\r\n  validateStandardSchema(config.definition, 'definition');\r\n\r\n  if (\r\n    typeof config.data.property !== 'string' ||\r\n    config.data.property.length === 0\r\n  ) {\r\n    throw new TypeError('data.property must be a non-empty string');\r\n  }\r\n\r\n  if (protectedPropertyNames.has(config.data.property)) {\r\n    throw new TypeError(\r\n      `data.property cannot overwrite protected property \"${config.data.property}\"`,\r\n    );\r\n  }\r\n}\r\n\r\nfunction formatIssuePath(path: StandardSchemaV1.Issue['path']) {\r\n  if (!path?.length) {\r\n    return '';\r\n  }\r\n\r\n  const keys = path.map((segment) =>\r\n    typeof segment === 'object' ? segment.key : segment,\r\n  );\r\n\r\n  return `${keys.map(String).join('.')}: `;\r\n}\r\n\r\nfunction parseSchema<Schema extends StandardSchemaV1>(\r\n  schema: Schema,\r\n  input: StandardSchemaV1.InferInput<Schema>,\r\n  subject: string,\r\n) {\r\n  const result = schema['~standard'].validate(input);\r\n\r\n  if (result instanceof Promise) {\r\n    throw new TypeError(`${subject} schema validation must be synchronous`);\r\n  }\r\n\r\n  if (result.issues) {\r\n    const details = result.issues\r\n      .map((issue) => `${formatIssuePath(issue.path)}${issue.message}`)\r\n      .join('; ');\r\n\r\n    throw new TypeError(`Invalid error ${subject}: ${details}`);\r\n  }\r\n\r\n  return result.value;\r\n}\r\n\r\nfunction parseDefinition<Schema extends StandardSchemaV1>(\r\n  schema: Schema,\r\n  definition: StandardSchemaV1.InferInput<Schema>,\r\n) {\r\n  const parsedDefinition = parseSchema(schema, definition, 'definition');\r\n\r\n  if (!isObjectLike(parsedDefinition)) {\r\n    throw new TypeError('definition schema must produce an object');\r\n  }\r\n\r\n  return parsedDefinition;\r\n}\r\n\r\nfunction assignProperties(\r\n  error: Error & Record<string, unknown>,\r\n  properties: object,\r\n  dataProperty: string,\r\n  data: unknown,\r\n) {\r\n  for (const key of Reflect.ownKeys(properties)) {\r\n    if (typeof key === 'string' && protectedPropertyNames.has(key)) {\r\n      throw new TypeError(`Cannot overwrite protected error property \"${key}\"`);\r\n    }\r\n\r\n    const descriptor = Object.getOwnPropertyDescriptor(properties, key);\r\n\r\n    if (!descriptor) {\r\n      continue;\r\n    }\r\n\r\n    if (\r\n      key === dataProperty &&\r\n      (!('value' in descriptor) || descriptor.value !== data)\r\n    ) {\r\n      throw new TypeError(`Cannot overwrite resolved data property \"${dataProperty}\"`);\r\n    }\r\n\r\n    Object.defineProperty(error, key, descriptor);\r\n  }\r\n}\r\n\r\n/**\r\n * Creates an error family with additional instance properties and typed JSON\r\n * serialization.\r\n *\r\n * @param config Defines the family, its public properties, and its serialized\r\n * representation.\r\n * @returns A callable factory with a shared `.Error` base class.\r\n *\r\n * @example\r\n * ```ts\r\n * const createApiError = createError({\r\n *   definition: z.object({ code: z.string() }),\r\n *   data: {\r\n *     property: 'context',\r\n *     resolve: ({ input }) => input,\r\n *   },\r\n *   message: ({ data, implementation }) => implementation(data),\r\n *   properties: ({ definition }) => ({ code: definition.code }),\r\n *   toJSON: (error) => ({\r\n *     code: error.code,\r\n *     context: error.context,\r\n *     message: error.message,\r\n *   }),\r\n * });\r\n * ```\r\n */\r\nexport function createError<\r\n  const Schema extends StandardSchemaV1,\r\n  const DataConfig extends CreateErrorConfig<Schema>['data'],\r\n  const MessageCallback extends CreateErrorConfig<Schema>['message'],\r\n  const Properties extends object,\r\n  Json,\r\n>(\r\n  config: SerializedCreateErrorConfig<\r\n    Schema,\r\n    ErrorConfigWithProperties<\r\n      Schema,\r\n      DataConfig,\r\n      MessageCallback,\r\n      Properties\r\n    >,\r\n    Json\r\n  >,\r\n): ErrorFamilyFactory<Schema, typeof config>;\r\n\r\n/**\r\n * Creates an error family with typed JSON serialization and no additional\r\n * instance properties.\r\n *\r\n * @param config Defines the family and its serialized representation.\r\n * @returns A callable factory with a shared `.Error` base class.\r\n *\r\n * @example\r\n * ```ts\r\n * const createLogError = createError({\r\n *   definition: z.object({ code: z.string() }),\r\n *   data: {\r\n *     property: 'details',\r\n *     resolve: ({ input }) => input,\r\n *   },\r\n *   message: ({ data, implementation }) => implementation(data),\r\n *   toJSON: (error) => ({\r\n *     details: error.details,\r\n *     message: error.message,\r\n *   }),\r\n * });\r\n * ```\r\n */\r\nexport function createError<\r\n  const Schema extends StandardSchemaV1,\r\n  const DataConfig extends CreateErrorConfig<Schema>['data'],\r\n  const MessageCallback extends CreateErrorConfig<Schema>['message'],\r\n  Json,\r\n>(\r\n  config: SerializedCreateErrorConfig<\r\n    Schema,\r\n    ErrorConfigWithoutProperties<Schema, DataConfig, MessageCallback>,\r\n    Json\r\n  >,\r\n): ErrorFamilyFactory<Schema, typeof config>;\r\n\r\n/**\r\n * Creates a configurable family of strongly typed error classes.\r\n *\r\n * Callback execution order is `data.resolve`, optional context validation,\r\n * `message`, then `properties`. Parsed definition output and constructor data\r\n * are inferred without explicit generic arguments or `as const`.\r\n *\r\n * @param config Defines the family's schema, data lifecycle, message, and\r\n * optional public properties.\r\n * @returns A callable factory with a shared `.Error` base class.\r\n *\r\n * @example\r\n * ```ts\r\n * const createRequestError = createError({\r\n *   definition: z.object({ code: z.string() }),\r\n *   data: {\r\n *     property: 'context',\r\n *     resolve: ({ input }) => input,\r\n *   },\r\n *   message: ({ data, implementation }) => implementation(data),\r\n *   properties: ({ definition }) => ({ code: definition.code }),\r\n * });\r\n * ```\r\n */\r\nexport function createError<\r\n  const Schema extends StandardSchemaV1,\r\n  const Config extends Omit<CreateErrorConfig<Schema>, 'definition'>,\r\n>(\r\n  config: ExactCreateErrorConfig<Schema, Config>,\r\n): ErrorFamilyFactory<Schema, typeof config>;\r\nexport function createError<\r\n  const Schema extends StandardSchemaV1,\r\n  const Config extends Omit<CreateErrorConfig<Schema>, 'definition'>,\r\n>(\r\n  config: ExactCreateErrorConfig<Schema, Config>,\r\n): ErrorFamilyFactory<Schema, typeof config> {\r\n  validateBlueprint(config as CreateErrorConfig<StandardSchemaV1>);\r\n\r\n  class FamilyError extends Error {\r\n    static invariant<Condition, Input>(\r\n      this: new (input: Input, options?: ErrorOptions) => Error,\r\n      condition: Condition,\r\n      input: Input | (() => Input),\r\n      options?: ErrorOptions,\r\n    ): asserts condition {\r\n      if (condition) {\r\n        return;\r\n      }\r\n\r\n      const resolvedInput =\r\n        typeof input === 'function' ? (input as () => Input)() : input;\r\n\r\n      throw new this(resolvedInput, options);\r\n    }\r\n\r\n    constructor(message: string, options?: ErrorOptions) {\r\n      super(message, options);\r\n      const name = new.target.name;\r\n      if (name) {\r\n        this.name = name;\r\n      }\r\n    }\r\n  }\r\n\r\n  if (config.toJSON) {\r\n    Object.defineProperty(FamilyError.prototype, 'toJSON', {\r\n      configurable: true,\r\n      value: function toJSON(this: Error & Record<string, unknown>) {\r\n        return config.toJSON?.(this as never);\r\n      },\r\n      writable: true,\r\n    });\r\n  }\r\n\r\n  function createDefinition<\r\n    const Definition extends StandardSchemaV1.InferInput<Schema>,\r\n  >(definition: Definition) {\r\n    const parsedDefinition = parseDefinition(config.definition, definition);\r\n\r\n    function createImplementation(\r\n      implementation: RuntimeImplementation,\r\n      contextSchema?: StandardSchemaV1,\r\n    ) {\r\n      return class extends FamilyError {\r\n        constructor(input: unknown, options?: ErrorOptions) {\r\n          const resolvedData = config.data.resolve({\r\n            definition: parsedDefinition,\r\n            input,\r\n          } as never);\r\n          const data = contextSchema\r\n            ? parseSchema(contextSchema, resolvedData, 'context')\r\n            : resolvedData;\r\n          const implementationWithDefinition: RuntimeImplementation = (\r\n            argument,\r\n          ) =>\r\n            implementation(\r\n              argument === data\r\n                ? argument\r\n                : includeDefinition(argument, parsedDefinition),\r\n            );\r\n          const message = config.message({\r\n            data,\r\n            definition: parsedDefinition,\r\n            implementation: implementationWithDefinition,\r\n          } as never);\r\n\r\n          super(message, options);\r\n\r\n          Object.defineProperty(this, config.data.property, {\r\n            configurable: true,\r\n            enumerable: true,\r\n            value: data,\r\n            writable: true,\r\n          });\r\n\r\n          const properties = config.properties?.({\r\n            data,\r\n            definition: parsedDefinition,\r\n            implementation: implementationWithDefinition,\r\n          } as never);\r\n\r\n          if (properties) {\r\n            assignProperties(\r\n              this as Error & Record<string, unknown>,\r\n              properties,\r\n              config.data.property,\r\n              data,\r\n            );\r\n          }\r\n        }\r\n      };\r\n    }\r\n\r\n    function implement(implementation: RuntimeImplementation) {\r\n      return createImplementation(implementation);\r\n    }\r\n\r\n    function defineContext<ContextSchema extends StandardSchemaV1>(\r\n      contextSchema: ContextSchema,\r\n    ) {\r\n      validateStandardSchema(contextSchema, 'context');\r\n\r\n      return {\r\n        implement(implementation: RuntimeImplementation) {\r\n          return createImplementation(implementation, contextSchema);\r\n        },\r\n      };\r\n    }\r\n\r\n    return {\r\n      defineContext,\r\n      implement,\r\n    };\r\n  }\r\n\r\n  return Object.assign(createDefinition, {\r\n    Error: FamilyError,\r\n  }) as unknown as ErrorFamilyFactory<Schema, typeof config>;\r\n}\r\n"],"mappings":"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"}

package/dist/create-error.d.cts

@@ -0,0 +1,101 @@
+import { BlueprintContext, BlueprintErrorTemplate, CreateErrorConfig, ErrorFamilyFactory } from "./types.cjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/create-error.d.ts
+type ErrorConfigBody<Schema extends StandardSchemaV1, DataConfig extends CreateErrorConfig<Schema>['data'], MessageCallback extends CreateErrorConfig<Schema>['message']> = {
+  data: DataConfig;
+  message: MessageCallback;
+};
+type ErrorConfigWithProperties<Schema extends StandardSchemaV1, DataConfig extends CreateErrorConfig<Schema>['data'], MessageCallback extends CreateErrorConfig<Schema>['message'], Properties extends object> = ErrorConfigBody<Schema, DataConfig, MessageCallback> & {
+  properties(context: BlueprintContext<Schema>): Properties;
+};
+type ErrorConfigWithoutProperties<Schema extends StandardSchemaV1, DataConfig extends CreateErrorConfig<Schema>['data'], MessageCallback extends CreateErrorConfig<Schema>['message']> = ErrorConfigBody<Schema, DataConfig, MessageCallback> & {
+  properties?: never;
+};
+type ExactCreateErrorConfig<Schema extends StandardSchemaV1, Config extends object> = {
+  definition: Schema;
+} & Config & (StandardSchemaV1.InferOutput<Schema> extends object ? unknown : {
+  definition: never;
+});
+type SerializedCreateErrorConfig<Schema extends StandardSchemaV1, Config extends object, Json> = ExactCreateErrorConfig<Schema, Config & {
+  toJSON(error: BlueprintErrorTemplate<NoInfer<Config>>): Json;
+}>;
+/**
+ * Creates an error family with additional instance properties and typed JSON
+ * serialization.
+ *
+ * @param config Defines the family, its public properties, and its serialized
+ * representation.
+ * @returns A callable factory with a shared `.Error` base class.
+ *
+ * @example
+ * ```ts
+ * const createApiError = createError({
+ *   definition: z.object({ code: z.string() }),
+ *   data: {
+ *     property: 'context',
+ *     resolve: ({ input }) => input,
+ *   },
+ *   message: ({ data, implementation }) => implementation(data),
+ *   properties: ({ definition }) => ({ code: definition.code }),
+ *   toJSON: (error) => ({
+ *     code: error.code,
+ *     context: error.context,
+ *     message: error.message,
+ *   }),
+ * });
+ * ```
+ */
+declare function createError<const Schema extends StandardSchemaV1, const DataConfig extends CreateErrorConfig<Schema>['data'], const MessageCallback extends CreateErrorConfig<Schema>['message'], const Properties extends object, Json>(config: SerializedCreateErrorConfig<Schema, ErrorConfigWithProperties<Schema, DataConfig, MessageCallback, Properties>, Json>): ErrorFamilyFactory<Schema, typeof config>;
+/**
+ * Creates an error family with typed JSON serialization and no additional
+ * instance properties.
+ *
+ * @param config Defines the family and its serialized representation.
+ * @returns A callable factory with a shared `.Error` base class.
+ *
+ * @example
+ * ```ts
+ * const createLogError = createError({
+ *   definition: z.object({ code: z.string() }),
+ *   data: {
+ *     property: 'details',
+ *     resolve: ({ input }) => input,
+ *   },
+ *   message: ({ data, implementation }) => implementation(data),
+ *   toJSON: (error) => ({
+ *     details: error.details,
+ *     message: error.message,
+ *   }),
+ * });
+ * ```
+ */
+declare function createError<const Schema extends StandardSchemaV1, const DataConfig extends CreateErrorConfig<Schema>['data'], const MessageCallback extends CreateErrorConfig<Schema>['message'], Json>(config: SerializedCreateErrorConfig<Schema, ErrorConfigWithoutProperties<Schema, DataConfig, MessageCallback>, Json>): ErrorFamilyFactory<Schema, typeof config>;
+/**
+ * Creates a configurable family of strongly typed error classes.
+ *
+ * Callback execution order is `data.resolve`, optional context validation,
+ * `message`, then `properties`. Parsed definition output and constructor data
+ * are inferred without explicit generic arguments or `as const`.
+ *
+ * @param config Defines the family's schema, data lifecycle, message, and
+ * optional public properties.
+ * @returns A callable factory with a shared `.Error` base class.
+ *
+ * @example
+ * ```ts
+ * const createRequestError = createError({
+ *   definition: z.object({ code: z.string() }),
+ *   data: {
+ *     property: 'context',
+ *     resolve: ({ input }) => input,
+ *   },
+ *   message: ({ data, implementation }) => implementation(data),
+ *   properties: ({ definition }) => ({ code: definition.code }),
+ * });
+ * ```
+ */
+declare function createError<const Schema extends StandardSchemaV1, const Config extends Omit<CreateErrorConfig<Schema>, 'definition'>>(config: ExactCreateErrorConfig<Schema, Config>): ErrorFamilyFactory<Schema, typeof config>;
+//#endregion
+export { createError };
+//# sourceMappingURL=create-error.d.cts.map

package/dist/create-error.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-error.d.cts","names":[],"sources":["../src/create-error.ts"],"sourcesContent":[],"mappings":";;;;KAWK,+BACY,qCACI,kBAAkB,yCACb,kBAAkB;QAEpC;EALH,OAAA,EAMM,eANS;CACH;KAQZ,yBAPkC,CAAA,eAQtB,gBARsB,EAAA,mBASlB,iBATkB,CASA,MATA,CAAA,CAAA,MAAA,CAAA,EAAA,wBAUb,iBAVa,CAUK,MAVL,CAAA,CAAA,SAAA,CAAA,EAAA,mBAAA,MAAA,CAAA,GAYnC,eAZmC,CAYnB,MAZmB,EAYX,UAZW,EAYC,eAZD,CAAA,GAAA;EAAlB,UAAA,CAAA,OAAA,EAaC,gBAbD,CAakB,MAblB,CAAA,CAAA,EAa4B,UAb5B;CACuB;KAevC,4BAfqB,CAAA,eAgBT,gBAhBS,EAAA,mBAiBL,iBAjBK,CAiBa,MAjBb,CAAA,CAAA,MAAA,CAAA,EAAA,wBAkBA,iBAlBA,CAkBkB,MAlBlB,CAAA,CAAA,SAAA,CAAA,CAAA,GAmBtB,eAnBsB,CAmBN,MAnBM,EAmBE,UAnBF,EAmBc,eAnBd,CAAA,GAAA;EAElB,UAAA,CAAA,EAAA,KAAA;CACG;KAoBN,sBApBqB,CAAA,eAqBT,gBArBS,EAAA,eAAA,MAAA,CAAA,GAAA;EAGrB,UAAA,EAqBS,MArBT;CACY,GAqBb,MArBa,GAAA,CAsBd,gBAAA,CAAiB,WAtBH,CAsBe,MAtBf,CAAA,SAAA,MAAA,GAAA,OAAA,GAAA;EACsB,UAAA,EAAA,KAAA;CAAlB,CAAA;KAyBhB,2BAxBuC,CAAA,eAyB3B,gBAzB2B,EAAA,eAAA,MAAA,EAAA,IAAA,CAAA,GA4BxC,sBA5BwC,CA6B1C,MA7B0C,EA8B1C,MA9B0C,GAAA;EAAlB,MAAA,CAAA,KAAA,EA+BR,sBA/BQ,CA+Be,OA/Bf,CA+BuB,MA/BvB,CAAA,CAAA,CAAA,EA+BkC,IA/BlC;CAEN,CAAA;;;;;;;;AACuC;;;;;;;;;;;AAOxC;;;;;;;AAUY;AAKd,iBAqLD,WArLC,CAAA,qBAsLM,gBAtLN,EAAA,yBAuLU,iBAvLV,CAuL4B,MAvL5B,CAAA,CAAA,MAAA,CAAA,EAAA,8BAwLe,iBAxLf,CAwLiC,MAxLjC,CAAA,CAAA,SAAA,CAAA,EAAA,yBAAA,MAAA,EAAA,IAAA,CAAA,CAAA,MAAA,EA4LP,2BA5LO,CA6Lb,MA7La,EA8Lb,yBA9La,CA+LX,MA/LW,EAgMX,UAhMW,EAiMX,eAjMW,EAkMX,UAlMW,CAAA,EAoMb,IApMa,CAAA,CAAA,EAsMd,kBAtMc,CAsMK,MAtML,EAAA,OAsMoB,MAtMpB,CAAA;;;;;;;;;AAqLjB;;;;;;;;;;;;;;;AAiBqC,iBAyBrB,WAzBqB,CAAA,qBA0Bd,gBA1Bc,EAAA,yBA2BV,iBA3BU,CA2BQ,MA3BR,CAAA,CAAA,MAAA,CAAA,EAAA,8BA4BL,iBA5BK,CA4Ba,MA5Bb,CAAA,CAAA,SAAA,CAAA,EAAA,IAAA,CAAA,CAAA,MAAA,EA+B3B,2BA/B2B,CAgCjC,MAhCiC,EAiCjC,4BAjCiC,CAiCJ,MAjCI,EAiCI,UAjCJ,EAiCgB,eAjChB,CAAA,EAkCjC,IAlCiC,CAAA,CAAA,EAoClC,kBApCkC,CAoCf,MApCe,EAAA,OAoCA,MApCA,CAAA;;;AAyBrC;;;;;;;;;;;;;;;;;AAqCA;;;;;AAIiC,iBAJjB,WAIiB,CAAA,qBAHV,gBAGU,EAAA,qBAFV,IAEU,CAFL,iBAEK,CAFa,MAEb,CAAA,EAAA,YAAA,CAAA,CAAA,CAAA,MAAA,EAAvB,sBAAuB,CAAA,MAAA,EAAQ,MAAR,CAAA,CAAA,EAC9B,kBAD8B,CACX,MADW,EAAA,OACI,MADJ,CAAA"}