{"version":3,"file":"assert.cjs","names":[],"sources":["../src/assert/_exports.ts"],"sourcesContent":["/**\n * ---header-docs-section---\n * # yummies/assert\n *\n * ## Description\n *\n * Runtime **assertions** for invariants, narrowing, and exhaustiveness. Helpers throw\n * {@link AssertionError} with an optional message (`string` or {@link MaybeFn}) so failing fast stays\n * explicit without a heavy assertion library. Use `assert.ok`, `assert.string`, `assert.defined`,\n * `assert.fail`, and the rest on the namespace export from the package entry.\n *\n * ## Usage\n *\n * ```ts\n * import { assert } from \"yummies/assert\";\n *\n * assert.ok(user.id, \"user id is required\");\n * assert.defined(maybeName);\n * assert.string(raw);\n * ```\n */\n\nimport { callFunction } from 'yummies/common';\nimport { typeGuard } from 'yummies/type-guard';\nimport type { AnyObject, Maybe, MaybeFn } from 'yummies/types';\n\n/**\n * Error thrown by assertion helpers in this module.\n */\nexport class AssertionError extends Error {\n  override name = 'AssertionError';\n}\n\nfunction resolveAssertMessage(\n  message: MaybeFn<string> | undefined,\n  fallback: string,\n): string {\n  if (message === undefined) {\n    return fallback;\n  }\n  return callFunction(message);\n}\n\n/**\n * Throws when `condition` is falsy; narrows the type when it is truthy.\n *\n * @param condition Value treated as a boolean guard.\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * assert.ok(user.id, \"user id is required\");\n * ```\n */\nexport function ok(\n  condition: unknown,\n  message?: MaybeFn<string>,\n): asserts condition {\n  if (typeGuard.isFalsy(condition)) {\n    throw new AssertionError(resolveAssertMessage(message, 'Assertion failed'));\n  }\n}\n\n/**\n * Same as {@link ok}; common alias for internal invariants (e.g. after optional checks).\n */\nexport const invariant: typeof ok = ok;\n\n/**\n * Throws when the value is `null` or `undefined`; otherwise narrows away nullish.\n *\n * @param value Possibly nullish value.\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * assert.defined(maybeName, \"name must be present\");\n * ```\n */\nexport function defined<T>(\n  value: Maybe<T>,\n  message?: MaybeFn<string>,\n): asserts value is NonNullable<T> {\n  if (!typeGuard.isDefined(value)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a defined value'),\n    );\n  }\n}\n\n/**\n * Throws when the value is `null`; allows `undefined` unless combined with other checks.\n *\n * @param value Value that may be `null`.\n * @param message Optional message or lazy message factory.\n */\nexport function notNull<T>(\n  value: T | null,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (typeGuard.isNull(value)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a non-null value'),\n    );\n  }\n}\n\n/**\n * Throws when the value is `undefined`.\n *\n * @param value Value that may be `undefined`.\n * @param message Optional message or lazy message factory.\n */\nexport function notUndefined<T>(\n  value: T | undefined,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (typeGuard.isUndefined(value)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a defined value'),\n    );\n  }\n}\n\n/**\n * Throws when `value` is not a string (primitive or `String` object); uses `typeGuard.isString`.\n *\n * @param value Value to narrow.\n * @param message Optional message or lazy message factory.\n */\nexport function string(\n  value: unknown,\n  message?: MaybeFn<string>,\n): asserts value is string {\n  if (!typeGuard.isString(value)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a string'),\n    );\n  }\n}\n\n/**\n * Throws when `value` is not a object (primitive or `AnyObject` object); uses `typeGuard.isObject`.\n *\n * @param value Value to narrow.\n * @param message Optional message or lazy message factory.\n */\nexport function object<T extends AnyObject = AnyObject>(\n  value: unknown,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (!typeGuard.isObject(value)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected an object'),\n    );\n  }\n}\n\n/**\n * Throws when `value` is not a object (primitive or `AnyObject` object); uses `typeGuard.isArray`.\n *\n * @param value Value to narrow.\n * @param message Optional message or lazy message factory.\n */\nexport function array<T extends any[] = any[]>(\n  value: unknown,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (!typeGuard.isArray(value)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected an array'),\n    );\n  }\n}\n\n/**\n * Throws when `value` is not a finite non-NaN number; uses `typeGuard.isNumber`.\n *\n * @param value Value to narrow.\n * @param message Optional message or lazy message factory.\n */\nexport function number(\n  value: unknown,\n  message?: MaybeFn<string>,\n): asserts value is number {\n  if (!typeGuard.isNumber(value)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a finite number'),\n    );\n  }\n}\n\n/**\n * Throws when `value` is not a boolean; uses `typeGuard.isBoolean`.\n *\n * @param value Value to narrow.\n * @param message Optional message or lazy message factory.\n */\nexport function boolean(\n  value: unknown,\n  message?: MaybeFn<string>,\n): asserts value is boolean {\n  if (!typeGuard.isBoolean(value)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a boolean'),\n    );\n  }\n}\n\n/**\n * Throws when `value` is not a symbol; uses `typeGuard.isSymbol`.\n *\n * @param value Value to narrow.\n * @param message Optional message or lazy message factory.\n */\nexport function symbol(\n  value: unknown,\n  message?: MaybeFn<string>,\n): asserts value is symbol {\n  if (!typeGuard.isSymbol(value)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a symbol'),\n    );\n  }\n}\n\n/**\n * Always throws; use for branches that must be impossible or as a typed “abort”.\n *\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * function parse(kind: \"a\" | \"b\") {\n *   if (kind === \"a\") return 1;\n *   if (kind === \"b\") return 2;\n *   assert.fail(\"unreachable\");\n * }\n * ```\n */\nexport function fail(message?: MaybeFn<string>): never {\n  throw new AssertionError(resolveAssertMessage(message, 'Unreachable'));\n}\n\n/**\n * Exhaustiveness helper: call with a `never` value when all union cases are handled.\n *\n * @param value Should be `never` when the type checker is satisfied.\n * @param message Optional message (this path always throws, so a lazy factory is unnecessary).\n */\nexport function unreachable(value: never, message?: string): never {\n  throw new AssertionError(\n    resolveAssertMessage(message, `Unexpected value: ${String(value)}`),\n  );\n}\n\n/**\n * Alias for {@link unreachable} (common name in switch exhaustiveness snippets).\n */\nexport { unreachable as never };\n\n/**\n * Throws when `value` is not an instance of `ctor`.\n *\n * @param value Value to check.\n * @param ctor Constructor used with `instanceof`.\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * assert.instanceOf(el, HTMLElement, \"expected a DOM element\");\n * ```\n */\nexport function instanceOf<T>(\n  value: unknown,\n  ctor: abstract new (...args: never[]) => T,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (!(value instanceof ctor)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, `Expected instance of ${ctor.name}`),\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,iBAAb,cAAoC,MAAM;CACxC,OAAgB;AAClB;AAEA,SAAS,qBACP,SACA,UACQ;CACR,IAAI,YAAY,KAAA,GACd,OAAO;CAET,QAAA,GAAA,eAAA,cAAoB,OAAO;AAC7B;;;;;;;;;;;;AAaA,SAAgB,GACd,WACA,SACmB;CACnB,IAAI,mBAAA,UAAU,QAAQ,SAAS,GAC7B,MAAM,IAAI,eAAe,qBAAqB,SAAS,kBAAkB,CAAC;AAE9E;;;;AAKA,IAAa,YAAuB;;;;;;;;;;;;AAapC,SAAgB,QACd,OACA,SACiC;CACjC,IAAI,CAAC,mBAAA,UAAU,UAAU,KAAK,GAC5B,MAAM,IAAI,eACR,qBAAqB,SAAS,0BAA0B,CAC1D;AAEJ;;;;;;;AAQA,SAAgB,QACd,OACA,SACoB;CACpB,IAAI,mBAAA,UAAU,OAAO,KAAK,GACxB,MAAM,IAAI,eACR,qBAAqB,SAAS,2BAA2B,CAC3D;AAEJ;;;;;;;AAQA,SAAgB,aACd,OACA,SACoB;CACpB,IAAI,mBAAA,UAAU,YAAY,KAAK,GAC7B,MAAM,IAAI,eACR,qBAAqB,SAAS,0BAA0B,CAC1D;AAEJ;;;;;;;AAQA,SAAgB,OACd,OACA,SACyB;CACzB,IAAI,CAAC,mBAAA,UAAU,SAAS,KAAK,GAC3B,MAAM,IAAI,eACR,qBAAqB,SAAS,mBAAmB,CACnD;AAEJ;;;;;;;AAQA,SAAgB,OACd,OACA,SACoB;CACpB,IAAI,CAAC,mBAAA,UAAU,SAAS,KAAK,GAC3B,MAAM,IAAI,eACR,qBAAqB,SAAS,oBAAoB,CACpD;AAEJ;;;;;;;AAQA,SAAgB,MACd,OACA,SACoB;CACpB,IAAI,CAAC,mBAAA,UAAU,QAAQ,KAAK,GAC1B,MAAM,IAAI,eACR,qBAAqB,SAAS,mBAAmB,CACnD;AAEJ;;;;;;;AAQA,SAAgB,OACd,OACA,SACyB;CACzB,IAAI,CAAC,mBAAA,UAAU,SAAS,KAAK,GAC3B,MAAM,IAAI,eACR,qBAAqB,SAAS,0BAA0B,CAC1D;AAEJ;;;;;;;AAQA,SAAgB,QACd,OACA,SAC0B;CAC1B,IAAI,CAAC,mBAAA,UAAU,UAAU,KAAK,GAC5B,MAAM,IAAI,eACR,qBAAqB,SAAS,oBAAoB,CACpD;AAEJ;;;;;;;AAQA,SAAgB,OACd,OACA,SACyB;CACzB,IAAI,CAAC,mBAAA,UAAU,SAAS,KAAK,GAC3B,MAAM,IAAI,eACR,qBAAqB,SAAS,mBAAmB,CACnD;AAEJ;;;;;;;;;;;;;;;AAgBA,SAAgB,KAAK,SAAkC;CACrD,MAAM,IAAI,eAAe,qBAAqB,SAAS,aAAa,CAAC;AACvE;;;;;;;AAQA,SAAgB,YAAY,OAAc,SAAyB;CACjE,MAAM,IAAI,eACR,qBAAqB,SAAS,qBAAqB,OAAO,KAAK,GAAG,CACpE;AACF;;;;;;;;;;;;;AAmBA,SAAgB,WACd,OACA,MACA,SACoB;CACpB,IAAI,EAAE,iBAAiB,OACrB,MAAM,IAAI,eACR,qBAAqB,SAAS,wBAAwB,KAAK,MAAM,CACnE;AAEJ"}