cipher-kit 2.0.0 → 2.1.1

package/dist/{chunk-3UX5MZ2P.cjs → chunk-X4CS7UXE.cjs}

@@ -30,22 +30,22 @@ var ENCRYPTION_ALGORITHMS = Object.freeze({
 function $isStr(x, min = 1) {
   return x !== null && x !== void 0 && typeof x === "string" && x.trim().length >= min;
 }
-function $isObj(x) {
+function $isPlainObj(x) {
   if (typeof x !== "object" || x === null || x === void 0) return false;
   const proto = Object.getPrototypeOf(x);
   return proto === Object.prototype || proto === null;
 }
-function $isLooseObj(x) {
+function $isObj(x) {
   return typeof x === "object" && x !== null && x !== void 0;
 }
 var expectedKeys = /* @__PURE__ */ new Set(["platform", "digest", "algorithm", "key"]);
 function $isSecretKey(x, platform) {
-  if (!$isLooseObj(x) || platform !== "node" && platform !== "web" || x.platform !== platform) return null;
+  if (!$isObj(x) || platform !== "node" && platform !== "web" || x.platform !== platform) return null;
   const keys = Object.keys(x);
   if (keys.length !== expectedKeys.size) return null;
   for (const key of keys) if (!expectedKeys.has(key)) return null;
   for (const key of expectedKeys) if (!Object.hasOwn(x, key)) return null;
-  if (typeof x.digest !== "string" || !(x.digest in DIGEST_ALGORITHMS) || typeof x.algorithm !== "string" || !(x.algorithm in ENCRYPTION_ALGORITHMS) || !$isLooseObj(x.key) || x.key.type !== "secret") {
+  if (typeof x.digest !== "string" || !(x.digest in DIGEST_ALGORITHMS) || typeof x.algorithm !== "string" || !(x.algorithm in ENCRYPTION_ALGORITHMS) || !$isObj(x.key) || x.key.type !== "secret") {
     return null;
   }
   const algorithm = ENCRYPTION_ALGORITHMS[x.algorithm];
@@ -55,7 +55,7 @@ function $isSecretKey(x, platform) {
     }
     return Object.freeze({ ...x, injected: algorithm });
   }
-  if (!$isLooseObj(x.key.algorithm) || x.key.algorithm.name !== algorithm.web || typeof x.key.algorithm.length === "number" && x.key.algorithm.length !== algorithm.keyBytes * 8 || typeof x.key.extractable !== "boolean" || !Array.isArray(x.key.usages) || x.key.usages.length !== 2 || !(x.key.usages.includes("encrypt") && x.key.usages.includes("decrypt"))) {
+  if (!$isObj(x.key.algorithm) || x.key.algorithm.name !== algorithm.web || typeof x.key.algorithm.length === "number" && x.key.algorithm.length !== algorithm.keyBytes * 8 || typeof x.key.extractable !== "boolean" || !Array.isArray(x.key.usages) || x.key.usages.length !== 2 || !(x.key.usages.includes("encrypt") && x.key.usages.includes("decrypt"))) {
     return null;
   }
   return Object.freeze({ ...x, injected: algorithm });
@@ -65,7 +65,7 @@ var ENCRYPTED_REGEX = Object.freeze({
   web: /^([^.]+)\.([^.]+)\.$/,
   general: /^([^.]+)\.([^.]+)(?:\.([^.]+))?\.$/
 });
-function matchPattern(data, format) {
+function matchEncryptedPattern(data, format) {
   if (typeof data !== "string") return false;
   if (!(format in ENCRYPTED_REGEX)) throw new Error(`Unknown format: ${format}`);
   return ENCRYPTED_REGEX[format].test(data);
@@ -73,7 +73,7 @@ function matchPattern(data, format) {
 
 // src/helpers/error.ts
 function $ok(result) {
-  if ($isObj(result)) return { success: true, ...result };
+  if ($isPlainObj(result)) return { success: true, ...result };
   return { success: true, result };
 }
 function $err(err) {
@@ -101,10 +101,22 @@ function title(platform, title2) {
 // src/helpers/object.ts
 function $stringifyObj(obj) {
   try {
-    if (!$isObj(obj)) return $err({ msg: "Invalid object", desc: "Input is not a plain object" });
+    if (!$isPlainObj(obj)) return $err({ msg: "JSON: Invalid object", desc: "Input is not a plain object" });
     return $ok(JSON.stringify(obj));
   } catch (error) {
-    return $err({ msg: "Utility: Stringify error", desc: $fmtError(error) });
+    return $err({ msg: "JSON: Stringify error", desc: $fmtError(error) });
+  }
+}
+function $parseToObj(str) {
+  try {
+    if (!$isStr(str)) return $err({ msg: "JSON: Invalid input", desc: "Input is not a valid string" });
+    const obj = JSON.parse(str);
+    if (!$isPlainObj(obj)) {
+      return $err({ msg: "JSON: Invalid object format", desc: "Parsed data is not a plain object" });
+    }
+    return $ok({ result: obj });
+  } catch (error) {
+    return $err({ msg: "JSON: Invalid format", desc: $fmtError(error) });
   }
 }
 function tryStringifyObj(obj) {
@@ -115,16 +127,6 @@ function stringifyObj(obj) {
   if (error) throw new Error($fmtResultErr(error));
   return result;
 }
-function $parseToObj(str) {
-  try {
-    if (!$isStr(str)) return $err({ msg: "Utility: Invalid input", desc: "Input is not a valid string" });
-    const obj = JSON.parse(str);
-    if (!$isObj(obj)) return $err({ msg: "Utility: Invalid object format", desc: "Parsed data is not a plain object" });
-    return $ok({ result: obj });
-  } catch (error) {
-    return $err({ msg: "Utility: Invalid format", desc: $fmtError(error) });
-  }
-}
 function tryParseToObj(str) {
   return $parseToObj(str);
 }
@@ -137,6 +139,7 @@ function parseToObj(str) {
 exports.$err = $err;
 exports.$fmtError = $fmtError;
 exports.$fmtResultErr = $fmtResultErr;
+exports.$isPlainObj = $isPlainObj;
 exports.$isSecretKey = $isSecretKey;
 exports.$isStr = $isStr;
 exports.$ok = $ok;
@@ -148,11 +151,11 @@ exports.ENCODING = ENCODING;
 exports.ENCRYPTED_REGEX = ENCRYPTED_REGEX;
 exports.ENCRYPTION_ALGORITHMS = ENCRYPTION_ALGORITHMS;
 exports.__export = __export;
-exports.matchPattern = matchPattern;
+exports.matchEncryptedPattern = matchEncryptedPattern;
 exports.parseToObj = parseToObj;
 exports.stringifyObj = stringifyObj;
 exports.title = title;
 exports.tryParseToObj = tryParseToObj;
 exports.tryStringifyObj = tryStringifyObj;
-//# sourceMappingURL=chunk-3UX5MZ2P.cjs.map
-//# sourceMappingURL=chunk-3UX5MZ2P.cjs.map
+//# sourceMappingURL=chunk-X4CS7UXE.cjs.map
+//# sourceMappingURL=chunk-X4CS7UXE.cjs.map

package/dist/chunk-X4CS7UXE.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/helpers/consts.ts","../src/helpers/validate.ts","../src/helpers/error.ts","../src/helpers/object.ts"],"names":["nodeCrypto","title"],"mappings":"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","file":"chunk-X4CS7UXE.cjs","sourcesContent":["export const ENCODING = Object.freeze([\"base64\", \"base64url\", \"hex\", \"utf8\", \"latin1\"] as const);\r\n\r\nexport const CIPHER_ENCODING = Object.freeze([\"base64\", \"base64url\", \"hex\"] as const);\r\n\r\nexport const DIGEST_ALGORITHMS = Object.freeze({\r\n  sha256: { node: \"sha256\", web: \"SHA-256\" },\r\n  sha384: { node: \"sha384\", web: \"SHA-384\" },\r\n  sha512: { node: \"sha512\", web: \"SHA-512\" },\r\n} as const);\r\n\r\nexport const ENCRYPTION_ALGORITHMS = Object.freeze({\r\n  aes256gcm: { keyBytes: 32, ivLength: 12, node: \"aes-256-gcm\", web: \"AES-GCM\" },\r\n  aes192gcm: { keyBytes: 24, ivLength: 12, node: \"aes-192-gcm\", web: \"AES-GCM\" },\r\n  aes128gcm: { keyBytes: 16, ivLength: 12, node: \"aes-128-gcm\", web: \"AES-GCM\" },\r\n} as const);\r\n","import nodeCrypto from \"node:crypto\";\r\nimport type { SecretKey } from \"~/helpers/types\";\r\nimport { DIGEST_ALGORITHMS, ENCRYPTION_ALGORITHMS } from \"./consts\";\r\n\r\nexport function $isStr(x: unknown, min = 1): x is string {\r\n  return x !== null && x !== undefined && typeof x === \"string\" && x.trim().length >= min;\r\n}\r\n\r\nexport function $isPlainObj<T extends object = Record<string, unknown>>(x: unknown): x is T {\r\n  if (typeof x !== \"object\" || x === null || x === undefined) return false;\r\n  const proto = Object.getPrototypeOf(x);\r\n  return proto === Object.prototype || proto === null;\r\n}\r\n\r\nexport function $isObj(x: unknown): x is Record<string, unknown> {\r\n  return typeof x === \"object\" && x !== null && x !== undefined;\r\n}\r\n\r\ntype InjectedSecretKey<Platform extends \"web\" | \"node\"> = SecretKey<Platform> & {\r\n  readonly injected: (typeof ENCRYPTION_ALGORITHMS)[keyof typeof ENCRYPTION_ALGORITHMS];\r\n};\r\n\r\nconst expectedKeys = new Set([\"platform\", \"digest\", \"algorithm\", \"key\"]);\r\n\r\nexport function $isSecretKey<Platform extends \"node\" | \"web\">(\r\n  x: unknown,\r\n  platform: Platform,\r\n): InjectedSecretKey<Platform> | null {\r\n  if (!$isObj(x) || (platform !== \"node\" && platform !== \"web\") || x.platform !== platform) return null;\r\n\r\n  const keys = Object.keys(x);\r\n  if (keys.length !== expectedKeys.size) return null;\r\n  for (const key of keys) if (!expectedKeys.has(key)) return null;\r\n  for (const key of expectedKeys) if (!Object.hasOwn(x, key)) return null;\r\n\r\n  if (\r\n    typeof x.digest !== \"string\" ||\r\n    !(x.digest in DIGEST_ALGORITHMS) ||\r\n    typeof x.algorithm !== \"string\" ||\r\n    !(x.algorithm in ENCRYPTION_ALGORITHMS) ||\r\n    !$isObj(x.key) ||\r\n    x.key.type !== \"secret\"\r\n  ) {\r\n    return null;\r\n  }\r\n\r\n  const algorithm = ENCRYPTION_ALGORITHMS[x.algorithm as keyof typeof ENCRYPTION_ALGORITHMS];\r\n\r\n  if (platform === \"node\") {\r\n    if (\r\n      !(x.key instanceof nodeCrypto.KeyObject) ||\r\n      (typeof x.key.symmetricKeySize === \"number\" && x.key.symmetricKeySize !== algorithm.keyBytes)\r\n    ) {\r\n      return null;\r\n    }\r\n    return Object.freeze({ ...x, injected: algorithm }) as InjectedSecretKey<Platform>;\r\n  }\r\n\r\n  if (\r\n    !$isObj(x.key.algorithm) ||\r\n    x.key.algorithm.name !== algorithm.web ||\r\n    (typeof x.key.algorithm.length === \"number\" && x.key.algorithm.length !== algorithm.keyBytes * 8) ||\r\n    typeof x.key.extractable !== \"boolean\" ||\r\n    !Array.isArray(x.key.usages) ||\r\n    x.key.usages.length !== 2 ||\r\n    !(x.key.usages.includes(\"encrypt\") && x.key.usages.includes(\"decrypt\"))\r\n  ) {\r\n    return null;\r\n  }\r\n  return Object.freeze({ ...x, injected: algorithm }) as InjectedSecretKey<Platform>;\r\n}\r\n\r\n/**\r\n * Regular expressions for encrypted data patterns.\r\n *\r\n * - **node**: `\"iv.cipher.tag.\"` (three dot-separated parts plus a trailing dot)\r\n * - **web**: `\"iv.cipherWithTag.\"` (two parts plus a trailing dot)\r\n * - **general**: accepts both shapes (2 or 3 parts) with a trailing dot\r\n *\r\n * Each part is any non-empty string without dots.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You have a secret code you want to check. Before you check it,\r\n * you make sure it looks how a secret code should look.\r\n */\r\nexport const ENCRYPTED_REGEX = Object.freeze({\r\n  node: /^([^.]+)\\.([^.]+)\\.([^.]+)\\.$/,\r\n  web: /^([^.]+)\\.([^.]+)\\.$/,\r\n  general: /^([^.]+)\\.([^.]+)(?:\\.([^.]+))?\\.$/,\r\n});\r\n\r\n/**\r\n * Checks if a string matches an expected encrypted payload shape.\r\n *\r\n * - **node**: `\"iv.cipher.tag.\"` (three dot-separated parts plus a trailing dot)\r\n * - **web**: `\"iv.cipherWithTag.\"` (two parts plus a trailing dot)\r\n * - **general**: accepts both shapes (2 or 3 parts) with a trailing dot\r\n *\r\n * Each part is any non-empty string without dots.\r\n *\r\n * This validates only the **shape**, not whether content is valid base64/hex, etc.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You have a secret code you want to check. Before you check it,\r\n * you make sure it looks how a secret code should look.\r\n *\r\n * @param data - The string to test.\r\n * @param format - Which layout to check: `'node'`, `'web'`, or `'general'`.\r\n * @returns `true` if the string matches the pattern; otherwise `false`.\r\n * @throws {Error} If an unknown `format` is provided.\r\n *\r\n * @example\r\n * ```ts\r\n * matchEncryptedPattern(\"abc.def.ghi.\", \"node\");    // true\r\n * matchEncryptedPattern(\"abc.def.\", \"web\");         // true\r\n * matchEncryptedPattern(\"abc.def.\", \"node\");        // false\r\n * matchEncryptedPattern(\"abc.def.ghi.\", \"general\"); // true\r\n * ```\r\n */\r\nexport function matchEncryptedPattern(data: string, format: \"node\" | \"web\" | \"general\"): boolean {\r\n  if (typeof data !== \"string\") return false;\r\n  if (!(format in ENCRYPTED_REGEX)) throw new Error(`Unknown format: ${format}`);\r\n  return ENCRYPTED_REGEX[format].test(data);\r\n}\r\n","import { $isPlainObj } from \"./validate\";\r\n\r\n/**\r\n * Standardized error object for the `Result` type.\r\n * Always has a brief `message` and a more detailed `description`.\r\n */\r\nexport interface ErrorStruct {\r\n  readonly message: string;\r\n  readonly description: string;\r\n}\r\n\r\ntype ReservedWords<Obj extends object> = \"success\" extends keyof Obj ? never : \"error\" extends keyof Obj ? never : Obj;\r\n\r\ntype OkType<T> = {\r\n  readonly success: true;\r\n  readonly error?: undefined;\r\n} & (T extends object ? ReservedWords<{ readonly [K in keyof T]: T[K] }> : { readonly result: T });\r\n\r\ntype ErrType<T> = {\r\n  readonly success: false;\r\n  readonly error: ErrorStruct;\r\n} & (T extends object ? ReservedWords<{ readonly [K in keyof T]?: undefined }> : { readonly result?: undefined });\r\n\r\n/**\r\n * Discriminated union for functions that can succeed or fail.\r\n *\r\n * - On **success**:\r\n *   - If `T` is an object - properties of `T` are **spread** into the result\r\n *     along with `success: true`.\r\n *   - Otherwise - `{ success: true, result: T }`.\r\n * - On **failure**: `{ success: false, error: E }`.\r\n *\r\n * @example\r\n * ```ts\r\n * // Primitive result\r\n * function getNum(): Result<number> {\r\n *   return $ok(42);\r\n * }\r\n * const r1 = getNum();\r\n * if (r1.success) console.log(r1.result); // 42\r\n *\r\n * // Object result (spread)\r\n * function getObject(): Result<{ name: string; age: number }> {\r\n *   return $ok({ name: 'Alice', age: 30 });\r\n * }\r\n * const r2 = getObject();\r\n * if (r2.success) console.log(r2.name, r2.age); // 'Alice' 30\r\n * ```\r\n */\r\nexport type Result<T> = OkType<T> | ErrType<T>;\r\n\r\nexport function $ok<T>(result: T): Result<T> {\r\n  if ($isPlainObj(result)) return { success: true, ...(result as T & object) } as Result<T>;\r\n  return { success: true, result } as Result<T>;\r\n}\r\n\r\ninterface ShortErrorStruct {\r\n  readonly msg: string;\r\n  readonly desc: string;\r\n}\r\n\r\nexport function $err(err: ShortErrorStruct | ErrorStruct): Result<never> {\r\n  return {\r\n    success: false,\r\n    error: {\r\n      message: \"msg\" in err ? err.msg : err.message,\r\n      description: \"desc\" in err ? err.desc : err.description,\r\n    },\r\n  } as Result<never>;\r\n}\r\n\r\nexport function $fmtError(error: unknown): string {\r\n  if (typeof error === \"string\") return error;\r\n  if (error instanceof Error) return error.message;\r\n  return String(error);\r\n}\r\n\r\nexport function $fmtResultErr(err: ErrorStruct | undefined): string {\r\n  if (!err) return \"Unknown error\";\r\n  return `${err.message} - ${err.description}`;\r\n}\r\n\r\nexport function title(platform: \"web\" | \"node\", title: string): string {\r\n  return `${platform === \"web\" ? \"Crypto Web API\" : \"Crypto NodeJS API\"} - ${title}`;\r\n}\r\n","import { $err, $fmtError, $fmtResultErr, $ok, type Result } from \"./error\";\r\nimport { $isPlainObj, $isStr } from \"./validate\";\r\n\r\nexport function $stringifyObj<T extends object = Record<string, unknown>>(obj: T): Result<string> {\r\n  try {\r\n    if (!$isPlainObj(obj)) return $err({ msg: \"JSON: Invalid object\", desc: \"Input is not a plain object\" });\r\n    return $ok(JSON.stringify(obj));\r\n  } catch (error) {\r\n    return $err({ msg: \"JSON: Stringify error\", desc: $fmtError(error) });\r\n  }\r\n}\r\n\r\nexport function $parseToObj<T extends object = Record<string, unknown>>(str: string): Result<{ result: T }> {\r\n  try {\r\n    if (!$isStr(str)) return $err({ msg: \"JSON: Invalid input\", desc: \"Input is not a valid string\" });\r\n    const obj = JSON.parse(str);\r\n\r\n    if (!$isPlainObj(obj)) {\r\n      return $err({ msg: \"JSON: Invalid object format\", desc: \"Parsed data is not a plain object\" });\r\n    }\r\n\r\n    return $ok({ result: obj as T });\r\n  } catch (error) {\r\n    return $err({ msg: \"JSON: Invalid format\", desc: $fmtError(error) });\r\n  }\r\n}\r\n\r\n/**\r\n * Safely serializes a plain object to JSON without throwing.\r\n *\r\n * Wraps `JSON.stringify` and returns a `Result` containing the JSON string or an error.\r\n * Only plain objects (POJOs) are accepted. Class instances, Maps, Sets, etc. are rejected.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You have a box of toys (your object) and take a photo of it (a JSON string)\r\n * so you can send it to a friend.\r\n *\r\n * @template T - Plain object type to serialize.\r\n * @param obj - The object to stringify (must be a plain object).\r\n * @returns A `Result` with the JSON string on success, or an error.\r\n *\r\n * @example\r\n * ```ts\r\n * const { result, error, success } = tryStringifyObj({ a: 1 });\r\n *\r\n * if (success) console.log(result); // \"{\\\"a\\\":1}\"\r\n * else console.error(error); // { message: \"...\", description: \"...\" }\r\n * ```\r\n */\r\nexport function tryStringifyObj<T extends object = Record<string, unknown>>(obj: T): Result<string> {\r\n  return $stringifyObj(obj);\r\n}\r\n\r\n/**\r\n * Serializes a plain object to JSON (throwing).\r\n *\r\n * Wraps `JSON.stringify` and returns the result or throws an error.\r\n * Only plain objects (POJOs) are accepted. Class instances, Maps, Sets, etc. are rejected.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You have a box of toys (your object) and take a photo of it (a JSON string)\r\n * so you can send it to a friend.\r\n *\r\n * @template T - Plain object type to serialize.\r\n * @param obj - The object to stringify (must be a plain object).\r\n * @returns JSON string representation of the object.\r\n * @throws {Error} If `obj` is not a plain object or serialization fails.\r\n *\r\n * @example\r\n * ```ts\r\n * const json = stringifyObj({ a: 1 }); // \"{\\\"a\\\":1}\"\r\n * ```\r\n */\r\nexport function stringifyObj<T extends object = Record<string, unknown>>(obj: T): string {\r\n  const { result, error } = $stringifyObj(obj);\r\n  if (error) throw new Error($fmtResultErr(error));\r\n  return result;\r\n}\r\n\r\n/**\r\n * Safely parses a JSON string to a plain object (non-throwing).\r\n *\r\n * Wraps `JSON.parse` and returns a `Result` containing the parsed object, or an error.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You rebuild your toy box (an object) from a photo you took (a JSON string).\r\n *\r\n * @template T - The expected object type.\r\n * @param str - The JSON string to parse.\r\n * @returns A `Result` with the parsed object on success, or an error.\r\n *\r\n * @example\r\n * ```ts\r\n * const {result, error, success} = tryParseToObj<{ a: number }>('{\"a\":1}');\r\n *\r\n * if (success) console.log(result); // { a: 1 }\r\n * else console.error(error) // { message: \"...\", description: \"...\" }\r\n * ```\r\n */\r\nexport function tryParseToObj<T extends object = Record<string, unknown>>(str: string): Result<{ result: T }> {\r\n  return $parseToObj<T>(str);\r\n}\r\n\r\n/**\r\n * Parses a JSON string to a plain object (throwing).\r\n *\r\n * Wraps `JSON.parse` and returns the parsed object, or throws on failure.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You rebuild your toy box (an object) from a photo you took (a JSON string).\r\n *\r\n * @template T - The expected object type.\r\n * @param str - The JSON string to parse.\r\n * @returns The parsed plain object.\r\n * @throws {Error} If the string can’t be parsed or doesn’t represent a plain object.\r\n *\r\n * @example\r\n * ```ts\r\n * const obj = parseToObj<{ a: number }>('{\"a\":1}'); // obj.a === 1\r\n * ```\r\n */\r\nexport function parseToObj<T extends object = Record<string, unknown>>(str: string): T {\r\n  const { result, error } = $parseToObj<T>(str);\r\n  if (error) throw new Error($fmtResultErr(error));\r\n  return result;\r\n}\r\n"]}

package/dist/{export-55tHE0Bw.d.cts → export-C4DbO5zM.d.ts}

@@ -1,4 +1,4 @@
-import { S as SecretKey, R as Result, d as CreateSecretKeyOptions, e as EncryptOptions, f as DecryptOptions, H as HashOptions, g as HashPasswordOptions, V as VerifyPasswordOptions, b as Encoding } from './validate-EHuJC5QQ.cjs';
+import { S as SecretKey, R as Result, d as CreateSecretKeyOptions, e as EncryptOptions, f as DecryptOptions, H as HashOptions, g as HashPasswordOptions, V as VerifyPasswordOptions, b as Encoding } from './validate-cJEdGlj1.js';
 
 /**
  * Type guard to check if the provided value is a SecretKey object for Web (Deno, Bun, Cloudflare included) environment.
@@ -8,6 +8,13 @@ import { S as SecretKey, R as Result, d as CreateSecretKeyOptions, e as EncryptO
  *
  * @param x - The value to check.
  * @returns True if the value is a SecretKey object for Web, false otherwise.
+ *
+ * @example
+ * ```ts
+ * isWebSecretKey(webKey); // true
+ * isWebSecretKey(nodeKey); // false
+ * isWebSecretKey({}); // false
+ * ```
  */
 declare function isWebSecretKey(x: unknown): x is SecretKey<"web">;
 /**
@@ -18,6 +25,14 @@ declare function isWebSecretKey(x: unknown): x is SecretKey<"web">;
  * The chance of two pets getting the same name tag is practically zero, and it's very hard to guess!
  *
  * @returns A `Result` containing the UUID string or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = tryGenerateUuid();
+ *
+ * if (success) console.log(result); // "..." (a UUID string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryGenerateUuid(): Result<string>;
 /**
@@ -29,6 +44,11 @@ declare function tryGenerateUuid(): Result<string>;
  *
  * @returns A UUID string.
  * @throws {Error} If UUID generation fails.
+ *
+ * @example
+ * ```ts
+ * const uuid = generateUuid(); // "..." (a UUID string)
+ * ```
  */
 declare function generateUuid(): string;
 /**
@@ -40,12 +60,20 @@ declare function generateUuid(): string;
  * Imagine you want to create a special key for future use to lock your treasure box (data).
  * So, you stir in some secret ingredients (like salt and info) to make sure your key is one-of-a-kind.
  *
- * @param secret - The input string to derive the `SecretKey` from.
+ * @param secret - The input string to derive the `SecretKey` from, must be at least 8 characters.
  * @param options.algorithm - The encryption algorithm to use (default: `'aes256gcm'`).
  * @param options.digest - The hash algorithm for HKDF (default: `'sha256'`).
  * @param options.salt - A salt string (default: `'cipher-kit-salt'`, must be ≥ 8 chars).
  * @param options.info - An info string (default: `'cipher-kit'`).
  * @returns A `Result` promise containing the derived `SecretKey` or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = await tryCreateSecretKey("my-secret");
+ *
+ * if (success) console.log(result); // SecretKey object
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryCreateSecretKey(secret: string, options?: CreateSecretKeyOptions): Promise<Result<{
     result: SecretKey<"web">;
@@ -59,13 +87,18 @@ declare function tryCreateSecretKey(secret: string, options?: CreateSecretKeyOpt
  * Imagine you want to create a special key for future use to lock your treasure box (data).
  * So, you stir in some secret ingredients (like salt and info) to make sure your key is one-of-a-kind.
  *
- * @param secret - The input string to derive the `SecretKey` from.
+ * @param secret - The input string to derive the `SecretKey` from, must be at least 8 characters.
  * @param options.algorithm - The encryption algorithm to use (default: `'aes256gcm'`).
  * @param options.digest - The hash algorithm for HKDF (default: `'sha256'`).
  * @param options.salt - A salt string (default: `'cipher-kit-salt'`, must be ≥ 8 chars).
  * @param options.info - An info string (default: `'cipher-kit'`).
  * @returns A promise of the derived `SecretKey`.
  * @throws {Error} If key derivation fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret"); // SecretKey object
+ * ```
  */
 declare function createSecretKey(secret: string, options?: CreateSecretKeyOptions): Promise<SecretKey<"web">>;
 /**
@@ -79,8 +112,17 @@ declare function createSecretKey(secret: string, options?: CreateSecretKeyOption
  *
  * @param data - A UTF-8 string to encrypt.
  * @param secretKey - The `SecretKey` object used for encryption.
- * @param options.encoding - The encoding format for the output ciphertext (default: `'base64url'`).
+ * @param options.outputEncoding - The encoding format for the output ciphertext (default: `'base64url'`).
  * @returns A `Result` promise containing the encrypted string in the specified format or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const {result, error, success} = await tryEncrypt("Hello, World!", secretKey);
+ *
+ * if (success) console.log(result); // "iv.cipherWithTag." (Encrypted string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryEncrypt(data: string, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<Result<string>>;
 /**
@@ -94,9 +136,15 @@ declare function tryEncrypt(data: string, secretKey: SecretKey<"web">, options?:
  *
  * @param data - A UTF-8 string to encrypt.
  * @param secretKey - The `SecretKey` object used for encryption.
- * @param options.encoding - The encoding format for the output ciphertext (default: `'base64url'`).
+ * @param options.outputEncoding - The encoding format for the output ciphertext (default: `'base64url'`).
  * @returns A promise with the encrypted string in the specified format.
  * @throws {Error} If the input data or key is invalid, or if encryption fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encrypt("Hello, World!", secretKey); // "iv.cipherWithTag." (Encrypted string)
+ * ```
  */
 declare function encrypt(data: string, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<string>;
 /**
@@ -110,8 +158,18 @@ declare function encrypt(data: string, secretKey: SecretKey<"web">, options?: En
  *
  * @param encrypted - The input string to decrypt, in the format "iv.cipherWithTag.".
  * @param secretKey - The `SecretKey` object used for decryption.
- * @param options.encoding - The encoding format for the input ciphertext (default: `'base64url'`).
+ * @param options.inputEncoding - The encoding format for the input ciphertext (default: `'base64url'`).
  * @returns A `Result` promise containing the decrypted UTF-8 string or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encrypt("Hello, World!", secretKey);
+ * const {result, error, success} = await tryDecrypt(encrypted, secretKey);
+ *
+ * if (success) console.log(result); // "Hello, World!"
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryDecrypt(encrypted: string, secretKey: SecretKey<"web">, options?: DecryptOptions): Promise<Result<string>>;
 /**
@@ -125,9 +183,16 @@ declare function tryDecrypt(encrypted: string, secretKey: SecretKey<"web">, opti
  *
  * @param encrypted - The input string to decrypt, in the format "iv.cipherWithTag.".
  * @param secretKey - The `SecretKey` object used for decryption.
- * @param options.encoding - The encoding format for the input ciphertext (default: `'base64url'`).
+ * @param options.inputEncoding - The encoding format for the input ciphertext (default: `'base64url'`).
  * @returns A promise with the decrypted UTF-8 string.
  * @throws {Error} If the input data or key is invalid, or if decryption fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encrypt("Hello, World!", secretKey);
+ * const decrypted = await decrypt(encrypted, secretKey); // "Hello, World!"
+ * ```
  */
 declare function decrypt(encrypted: string, secretKey: SecretKey<"web">, options?: DecryptOptions): Promise<string>;
 /**
@@ -142,12 +207,22 @@ declare function decrypt(encrypted: string, secretKey: SecretKey<"web">, options
  * So, you take a picture of your toy box (convert it to JSON), and scramble that with
  * your special key, creating a jumbled code that only someone with the right key can read.
  *
- * @param data - A plain object to encrypt.
+ * @template T - The type of the plain object to encrypt.
+ * @param obj - A plain object to encrypt.
  * @param secretKey - The `SecretKey` object used for encryption.
- * @param options.encoding - The encoding format for the output ciphertext (default: `'base64url'`).
+ * @param options.outputEncoding - The encoding format for the output ciphertext (default: `'base64url'`).
  * @returns A `Result` promise containing the encrypted string in the specified format or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const {result, error, success} = await tryEncryptObj({ a: 1 }, secretKey);
+ *
+ * if (success) console.log(result); // "iv.cipherWithTag." (Encrypted string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
-declare function tryEncryptObj<T extends object = Record<string, unknown>>(data: T, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<Result<string>>;
+declare function tryEncryptObj<T extends object = Record<string, unknown>>(obj: T, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<Result<string>>;
 /**
  * Encrypts a plain object using the provided `SecretKey` (throwing).
  *
@@ -160,15 +235,22 @@ declare function tryEncryptObj<T extends object = Record<string, unknown>>(data:
  * So, you take a picture of your toy box (convert it to JSON), and scramble that with
  * your special key, creating a jumbled code that only someone with the right key can read.
  *
- * @param data - A plain object to encrypt.
+ * @template T - The type of the plain object to encrypt.
+ * @param obj - A plain object to encrypt.
  * @param secretKey - The `SecretKey` object used for encryption.
- * @param options.encoding - The encoding format for the output ciphertext (default: `'base64url'`).
+ * @param options.outputEncoding - The encoding format for the output ciphertext (default: `'base64url'`).
  * @returns A promise with the encrypted string in the specified format.
  * @throws {Error} If the input data or key is invalid, or if encryption fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encryptObj({ a: 1 }, secretKey); // "iv.cipherWithTag." (Encrypted string)
+ * ```
  */
-declare function encryptObj<T extends object = Record<string, unknown>>(data: T, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<string>;
+declare function encryptObj<T extends object = Record<string, unknown>>(obj: T, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<string>;
 /**
- * Safely decrypts an encrypted JSON string into an object (non-throwing).
+ * Safely decrypts an encrypted JSON string into a plain object (non-throwing).
  *
  * Expects input in the format `"iv.cipherWithTag."` and returns a plain object.
  *
@@ -179,14 +261,24 @@ declare function encryptObj<T extends object = Record<string, unknown>>(data: T,
  * @template T - The expected shape of the decrypted object.
  * @param encrypted - The encrypted string (format: `"iv.cipherWithTag."`).
  * @param secretKey - The `SecretKey` used for decryption.
- * @param options.encoding - Input ciphertext encoding (default: `'base64url'`).
+ * @param options.inputEncoding - Input ciphertext encoding (default: `'base64url'`).
  * @returns A `Result` promise with the decrypted object on success, or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encryptObj({ a: 1 }, secretKey);
+ * const {result, error, success} = await tryDecryptObj<{ a: number }>(encrypted, secretKey);
+ *
+ * if (success) console.log(result); // { a: 1 }
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryDecryptObj<T extends object = Record<string, unknown>>(encrypted: string, secretKey: SecretKey<"web">, options?: DecryptOptions): Promise<Result<{
     result: T;
 }>>;
 /**
- * Decrypts an encrypted JSON string into an object (throwing).
+ * Decrypts an encrypted JSON string into a plain object (throwing).
  *
  * Expects input in the format `"iv.cipherWithTag."` and returns a plain object.
  *
@@ -197,9 +289,16 @@ declare function tryDecryptObj<T extends object = Record<string, unknown>>(encry
  * @template T - The expected shape of the decrypted object.
  * @param encrypted - The encrypted string (format: `"iv.cipherWithTag."`).
  * @param secretKey - The `SecretKey` used for decryption.
- * @param options.encoding - Input ciphertext encoding (default: `'base64url'`).
+ * @param options.inputEncoding - Input ciphertext encoding (default: `'base64url'`).
  * @returns A promise with the decrypted object.
  * @throws {Error} If decryption or JSON parsing fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encryptObj({ a: 1 }, secretKey);
+ * const obj = await decryptObj<{ a: number }>(encrypted, secretKey); // obj.a === 1
+ * ```
  */
 declare function decryptObj<T extends object = Record<string, unknown>>(encrypted: string, secretKey: SecretKey<"web">, options?: DecryptOptions): Promise<T>;
 /**
@@ -214,8 +313,16 @@ declare function decryptObj<T extends object = Record<string, unknown>>(encrypte
  *
  * @param data - The input string to hash.
  * @param options.digest - Hash algorithm (`'sha256' | 'sha384' | 'sha512'`, default: `'sha256'`).
- * @param options.encoding - Output encoding (`'base64' | 'base64url' | 'hex'`, default: `'base64url'`).
+ * @param options.outputEncoding - Output encoding (`'base64' | 'base64url' | 'hex'`, default: `'base64url'`).
  * @returns A `Result` promise with the hash string or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = await tryHash("my data");
+ *
+ * if (success) console.log(result); // "..." (Hashed string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryHash(data: string, options?: HashOptions): Promise<Result<string>>;
 /**
@@ -230,9 +337,14 @@ declare function tryHash(data: string, options?: HashOptions): Promise<Result<st
  *
  * @param data - The input string to hash.
  * @param options.digest - Hash algorithm (`'sha256' | 'sha384' | 'sha512'`, default: `'sha256'`).
- * @param options.encoding - Output encoding (`'base64' | 'base64url' | 'hex'`, default: `'base64url'`).
+ * @param options.outputEncoding - Output encoding (`'base64' | 'base64url' | 'hex'`, default: `'base64url'`).
  * @returns A promise of the hashed string.
  * @throws {Error} If input is invalid or hashing fails.
+ *
+ * @example
+ * ```ts
+ * const hashed = await hash("my data"); // "..." (Hashed string)
+ * ```
  */
 declare function hash(data: string, options?: HashOptions): Promise<string>;
 /**
@@ -247,14 +359,22 @@ declare function hash(data: string, options?: HashOptions): Promise<string>;
  *
  * @param password - The password to hash.
  * @param options.digest - Hash algorithm (`'sha256' | 'sha384' | 'sha512'`; default: `'sha512'`).
- * @param options.encoding - Output encoding (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
+ * @param options.outputEncoding - Output encoding (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
  * @param options.saltLength - Length of the random salt in bytes (default: `16` bytes, min: `8` bytes).
  * @param options.iterations - Number of iterations (default: `320000`, min: `1000`).
  * @param options.keyLength - Length of the derived key in bytes (default: `64` bytes, min: `16` bytes).
- * @returns A `Result` promise with `{ hash, salt }` or an error.
+ * @returns A `Result` promise with `{ result, salt }` or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = await tryHashPassword("my-password");
+ *
+ * if (success) console.log(result, salt); // "..." (hashed password), "..." (salt)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryHashPassword(password: string, options?: HashPasswordOptions): Promise<Result<{
-    hash: string;
+    result: string;
     salt: string;
 }>>;
 /**
@@ -269,15 +389,20 @@ declare function tryHashPassword(password: string, options?: HashPasswordOptions
  *
  * @param password - The password to hash.
  * @param options.digest - Hash algorithm (`'sha256' | 'sha384' | 'sha512'`; default: `'sha512'`).
- * @param options.encoding - Output encoding (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
+ * @param options.outputEncoding - Output encoding (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
  * @param options.saltLength - Length of the random salt in bytes (default: `16` bytes, min: `8` bytes).
  * @param options.iterations - Number of iterations (default: `320000`, min: `1000`).
  * @param options.keyLength - Length of the derived key in bytes (default: `64` bytes, min: `16` bytes).
- * @returns A promise with `{ hash, salt }` for storage.
+ * @returns A promise with `{ result, salt }` for storage.
  * @throws {Error} If inputs are invalid or hashing fails.
+ *
+ * @example
+ * ```ts
+ * const {result, salt} = await hashPassword("my-password"); // "..." (hashed password), "..." (salt)
+ * ```
  */
 declare function hashPassword(password: string, options?: HashPasswordOptions): Promise<{
-    hash: string;
+    result: string;
     salt: string;
 }>;
 /**
@@ -293,10 +418,18 @@ declare function hashPassword(password: string, options?: HashPasswordOptions):
  * @param hashedPassword - The stored hash (encoded).
  * @param salt - The stored salt (encoded).
  * @param options.digest - Hash algorithm used during hashing (`'sha256' | 'sha384' | 'sha512'`; default: `'sha512'`).
- * @param options.encoding - Encoding of the stored hash and salt (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
+ * @param options.inputEncoding - Encoding of the stored hash and salt (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
  * @param options.iterations - Number of iterations used during hashing (default: `320000`).
  * @param options.keyLength - Length of the derived key in bytes used during hashing (default: `64` bytes).
  * @returns A promise of boolean, `true` if the password matches, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * const {result, salt} = await hashPassword("my-password");
+ *
+ * await verifyPassword("my-password", result, salt); // true
+ * await verifyPassword("wrong-password", result, salt); // false
+ * ```
  */
 declare function verifyPassword(password: string, hashedPassword: string, salt: string, options?: VerifyPasswordOptions): Promise<boolean>;
 /**
@@ -310,6 +443,14 @@ declare function verifyPassword(password: string, hashedPassword: string, salt:
  * @param data - The input string to convert.
  * @param inputEncoding - The encoding of the input string (default: `'utf8'`).
  * @returns A `Result` with `{ result: Uint8Array }` or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = tryConvertStrToBytes("Hello", "utf8");
+ *
+ * if (success) console.log(result); // Uint8Array([...])
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryConvertStrToBytes(data: string, inputEncoding?: Encoding): Result<{
     result: Uint8Array<ArrayBuffer>;
@@ -326,6 +467,11 @@ declare function tryConvertStrToBytes(data: string, inputEncoding?: Encoding): R
  * @param inputEncoding - The encoding of the input string (default: `'utf8'`).
  * @returns A `Uint8Array` containing the bytes.
  * @throws {Error} If input is invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const bytes = convertStrToBytes("Hello", "utf8"); // Uint8Array([...])
+ * ```
  */
 declare function convertStrToBytes(data: string, inputEncoding?: Encoding): Uint8Array<ArrayBuffer>;
 /**
@@ -339,6 +485,15 @@ declare function convertStrToBytes(data: string, inputEncoding?: Encoding): Uint
  * @param data - The `Uint8Array` or `ArrayBuffer` to convert.
  * @param outputEncoding - The output encoding (default: `'utf8'`).
  * @returns A `Result` with the string or an error.
+ *
+ * @example
+ * ```ts
+ * const bytes = convertStrToBytes("Hello", "utf8"); // Uint8Array([...])
+ * const {result, error, success} = tryConvertBytesToStr(bytes, "utf8");
+ *
+ * if (success) console.log(result); // "Hello"
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryConvertBytesToStr(data: Uint8Array | ArrayBuffer, outputEncoding?: Encoding): Result<string>;
 /**
@@ -353,6 +508,12 @@ declare function tryConvertBytesToStr(data: Uint8Array | ArrayBuffer, outputEnco
  * @param outputEncoding - The output encoding (default: `'utf8'`).
  * @returns The encoded string.
  * @throws {Error} If input is invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const bytes = convertStrToBytes("Hello", "utf8"); // Uint8Array([...])
+ * const str = convertBytesToStr(bytes, "utf8"); // "Hello"
+ * ```
  */
 declare function convertBytesToStr(data: Uint8Array | ArrayBuffer, outputEncoding?: Encoding): string;
 /**
@@ -367,6 +528,14 @@ declare function convertBytesToStr(data: Uint8Array | ArrayBuffer, outputEncodin
  * @param from - The current encoding of `data`.
  * @param to - The target encoding for `data`.
  * @returns A `Result` with a string or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = tryConvertEncoding("Hello", "utf8", "base64url");
+ *
+ * if (success) console.log(result); // "..." (Base64url encoded string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryConvertEncoding(data: string, from: Encoding, to: Encoding): Result<string>;
 /**
@@ -382,6 +551,11 @@ declare function tryConvertEncoding(data: string, from: Encoding, to: Encoding):
  * @param to - The target encoding for `data`.
  * @returns The converted string.
  * @throws {Error} If encodings are invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const base64url = convertEncoding("Hello", "utf8", "base64url"); // "..." (Base64url encoded string)
+ * ```
  */
 declare function convertEncoding(data: string, from: Encoding, to: Encoding): string;