@ppabari/strio 1.0.2 → 1.1.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { R as RandomStringOptions, E as EntropyResult, V as ValidateOptions, c as ValidationResult } from './zod-CINbFpp9.cjs';
-export { a as RandomStringResult, b as RandomStringSchemaOptions, S as StartWith, r as randomStringSchema } from './zod-CINbFpp9.cjs';
+import { R as RandomStringOptions, E as EntropyResult, V as ValidateOptions, a as ValidationResult } from './zod-IWq12GIY.cjs';
+export { b as RandomStringResult, c as RandomStringSchemaOptions, S as StartWith, r as randomStringSchema } from './zod-IWq12GIY.cjs';
 
 /**
  * short-id.ts
@@ -347,6 +347,54 @@ declare function estimateEntropy(options?: RandomStringOptions): EntropyResult;
  */
 declare function validateRandomString(str: string, options?: ValidateOptions): ValidationResult;
 
+/**
+ * compat.ts
+ * Runtime environment & version compatibility checks.
+ *
+ * `@ppabari/strio` depends on the Web Crypto API (`crypto.getRandomValues`),
+ * which is available natively in Node >=18, all modern browsers, Deno, Bun,
+ * and edge runtimes. These helpers let applications verify — at startup or in
+ * a health check — that the current runtime can support secure generation,
+ * and surface a clear message when it cannot.
+ */
+/** The minimum Node.js major version supported by this package. */
+declare const MIN_NODE_VERSION = 18;
+type Runtime = 'node' | 'deno' | 'bun' | 'browser' | 'workerd' | 'unknown';
+interface CompatibilityResult {
+    /** `true` when the runtime can support secure string generation. */
+    ok: boolean;
+    /** Whether `crypto.getRandomValues` is available. */
+    cryptoAvailable: boolean;
+    /** Best-effort detected runtime. */
+    runtime: Runtime;
+    /** Node.js version string (e.g. `'20.11.0'`), when running on Node. */
+    nodeVersion?: string;
+    /** Human-readable warnings; empty when fully compatible. */
+    warnings: string[];
+}
+/**
+ * Inspect the current runtime and report whether `@ppabari/strio` can perform
+ * secure string generation. Never throws.
+ *
+ * @example
+ * import { checkCompatibility } from '@ppabari/strio';
+ *
+ * const report = checkCompatibility();
+ * if (!report.ok) console.warn(report.warnings.join('\n'));
+ */
+declare function checkCompatibility(): CompatibilityResult;
+/**
+ * Assert that the current runtime is compatible, throwing a descriptive error
+ * otherwise. Call this at startup to fail fast instead of at first use.
+ *
+ * @throws {Error} when the runtime cannot support secure generation.
+ *
+ * @example
+ * import { assertCompatible } from '@ppabari/strio';
+ * assertCompatible(); // throws on an unsupported runtime
+ */
+declare function assertCompatible(): void;
+
 /**
  * charset-aliases.ts
  * Named character set aliases for common encoding schemes.
@@ -882,4 +930,4 @@ declare function generateRandomString(options: RandomStringOptions & {
 }): string[];
 declare function generateRandomStringAsync(options?: RandomStringOptions): Promise<string | string[]>;
 
-export { type ApiKeyOptions, type ApiKeyResult, WORD_LIST as BUILT_IN_WORD_LIST, type Base64Variant, CHARSET_ALIASES, type CharsetAlias, EntropyResult, type ExpiringTokenOptions, type ExpiringTokenResult, type JwtAlgorithm, type JwtSecretFormat, type JwtSecretOptions, type JwtSecretResult, type MaskSecretOptions, type OtpOptions, type OtpResult, PRESETS, type PassphraseOptions, type PassphraseResult, type PresetName, RandomStringOptions, type ShortIdOptions, type ShortIdValidateOptions, type ShortIdValidateResult, type TokenVerifyResult, ValidateOptions, ValidationResult, estimateEntropy, generateAesKey, generateApiKey, generateBase64Key, generateBytes, generateCookieSecret, generateDjangoSecretKey, generateExpiringToken, generateHexKey, generateId, generateJwtSecret, generateNextAuthSecret, generateOtp, generatePassphrase, generateRailsSecretKeyBase, generateRandomString, generateRandomStringAsync, maskSecret, randomStringStream, resolveCharsetAlias, take, takeWhere, timingSafeEqual, uniqueRandomStringStream, validateId, validateRandomString, verifyToken };
+export { type ApiKeyOptions, type ApiKeyResult, WORD_LIST as BUILT_IN_WORD_LIST, type Base64Variant, CHARSET_ALIASES, type CharsetAlias, type CompatibilityResult, EntropyResult, type ExpiringTokenOptions, type ExpiringTokenResult, type JwtAlgorithm, type JwtSecretFormat, type JwtSecretOptions, type JwtSecretResult, MIN_NODE_VERSION, type MaskSecretOptions, type OtpOptions, type OtpResult, PRESETS, type PassphraseOptions, type PassphraseResult, type PresetName, RandomStringOptions, type Runtime, type ShortIdOptions, type ShortIdValidateOptions, type ShortIdValidateResult, type TokenVerifyResult, ValidateOptions, ValidationResult, assertCompatible, checkCompatibility, estimateEntropy, generateAesKey, generateApiKey, generateBase64Key, generateBytes, generateCookieSecret, generateDjangoSecretKey, generateExpiringToken, generateHexKey, generateId, generateJwtSecret, generateNextAuthSecret, generateOtp, generatePassphrase, generateRailsSecretKeyBase, generateRandomString, generateRandomStringAsync, maskSecret, randomStringStream, resolveCharsetAlias, take, takeWhere, timingSafeEqual, uniqueRandomStringStream, validateId, validateRandomString, verifyToken };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as RandomStringOptions, E as EntropyResult, V as ValidateOptions, c as ValidationResult } from './zod-CINbFpp9.js';
-export { a as RandomStringResult, b as RandomStringSchemaOptions, S as StartWith, r as randomStringSchema } from './zod-CINbFpp9.js';
+import { R as RandomStringOptions, E as EntropyResult, V as ValidateOptions, a as ValidationResult } from './zod-IWq12GIY.js';
+export { b as RandomStringResult, c as RandomStringSchemaOptions, S as StartWith, r as randomStringSchema } from './zod-IWq12GIY.js';
 
 /**
  * short-id.ts
@@ -347,6 +347,54 @@ declare function estimateEntropy(options?: RandomStringOptions): EntropyResult;
  */
 declare function validateRandomString(str: string, options?: ValidateOptions): ValidationResult;
 
+/**
+ * compat.ts
+ * Runtime environment & version compatibility checks.
+ *
+ * `@ppabari/strio` depends on the Web Crypto API (`crypto.getRandomValues`),
+ * which is available natively in Node >=18, all modern browsers, Deno, Bun,
+ * and edge runtimes. These helpers let applications verify — at startup or in
+ * a health check — that the current runtime can support secure generation,
+ * and surface a clear message when it cannot.
+ */
+/** The minimum Node.js major version supported by this package. */
+declare const MIN_NODE_VERSION = 18;
+type Runtime = 'node' | 'deno' | 'bun' | 'browser' | 'workerd' | 'unknown';
+interface CompatibilityResult {
+    /** `true` when the runtime can support secure string generation. */
+    ok: boolean;
+    /** Whether `crypto.getRandomValues` is available. */
+    cryptoAvailable: boolean;
+    /** Best-effort detected runtime. */
+    runtime: Runtime;
+    /** Node.js version string (e.g. `'20.11.0'`), when running on Node. */
+    nodeVersion?: string;
+    /** Human-readable warnings; empty when fully compatible. */
+    warnings: string[];
+}
+/**
+ * Inspect the current runtime and report whether `@ppabari/strio` can perform
+ * secure string generation. Never throws.
+ *
+ * @example
+ * import { checkCompatibility } from '@ppabari/strio';
+ *
+ * const report = checkCompatibility();
+ * if (!report.ok) console.warn(report.warnings.join('\n'));
+ */
+declare function checkCompatibility(): CompatibilityResult;
+/**
+ * Assert that the current runtime is compatible, throwing a descriptive error
+ * otherwise. Call this at startup to fail fast instead of at first use.
+ *
+ * @throws {Error} when the runtime cannot support secure generation.
+ *
+ * @example
+ * import { assertCompatible } from '@ppabari/strio';
+ * assertCompatible(); // throws on an unsupported runtime
+ */
+declare function assertCompatible(): void;
+
 /**
  * charset-aliases.ts
  * Named character set aliases for common encoding schemes.
@@ -882,4 +930,4 @@ declare function generateRandomString(options: RandomStringOptions & {
 }): string[];
 declare function generateRandomStringAsync(options?: RandomStringOptions): Promise<string | string[]>;
 
-export { type ApiKeyOptions, type ApiKeyResult, WORD_LIST as BUILT_IN_WORD_LIST, type Base64Variant, CHARSET_ALIASES, type CharsetAlias, EntropyResult, type ExpiringTokenOptions, type ExpiringTokenResult, type JwtAlgorithm, type JwtSecretFormat, type JwtSecretOptions, type JwtSecretResult, type MaskSecretOptions, type OtpOptions, type OtpResult, PRESETS, type PassphraseOptions, type PassphraseResult, type PresetName, RandomStringOptions, type ShortIdOptions, type ShortIdValidateOptions, type ShortIdValidateResult, type TokenVerifyResult, ValidateOptions, ValidationResult, estimateEntropy, generateAesKey, generateApiKey, generateBase64Key, generateBytes, generateCookieSecret, generateDjangoSecretKey, generateExpiringToken, generateHexKey, generateId, generateJwtSecret, generateNextAuthSecret, generateOtp, generatePassphrase, generateRailsSecretKeyBase, generateRandomString, generateRandomStringAsync, maskSecret, randomStringStream, resolveCharsetAlias, take, takeWhere, timingSafeEqual, uniqueRandomStringStream, validateId, validateRandomString, verifyToken };
+export { type ApiKeyOptions, type ApiKeyResult, WORD_LIST as BUILT_IN_WORD_LIST, type Base64Variant, CHARSET_ALIASES, type CharsetAlias, type CompatibilityResult, EntropyResult, type ExpiringTokenOptions, type ExpiringTokenResult, type JwtAlgorithm, type JwtSecretFormat, type JwtSecretOptions, type JwtSecretResult, MIN_NODE_VERSION, type MaskSecretOptions, type OtpOptions, type OtpResult, PRESETS, type PassphraseOptions, type PassphraseResult, type PresetName, RandomStringOptions, type Runtime, type ShortIdOptions, type ShortIdValidateOptions, type ShortIdValidateResult, type TokenVerifyResult, ValidateOptions, ValidationResult, assertCompatible, checkCompatibility, estimateEntropy, generateAesKey, generateApiKey, generateBase64Key, generateBytes, generateCookieSecret, generateDjangoSecretKey, generateExpiringToken, generateHexKey, generateId, generateJwtSecret, generateNextAuthSecret, generateOtp, generatePassphrase, generateRailsSecretKeyBase, generateRandomString, generateRandomStringAsync, maskSecret, randomStringStream, resolveCharsetAlias, take, takeWhere, timingSafeEqual, uniqueRandomStringStream, validateId, validateRandomString, verifyToken };

package/dist/index.js

@@ -1429,6 +1429,54 @@ function validatePattern(str, pattern) {
   return errors;
 }
 
+// src/compat.ts
+var MIN_NODE_VERSION = 18;
+function detectRuntime() {
+  const g = globalThis;
+  if (typeof g.Deno !== "undefined") return { runtime: "deno" };
+  if (typeof g.Bun !== "undefined") return { runtime: "bun" };
+  if (typeof g.process !== "undefined" && g.process?.versions?.node) {
+    return { runtime: "node", nodeVersion: String(g.process.versions.node) };
+  }
+  if (typeof g.WebSocketPair !== "undefined") return { runtime: "workerd" };
+  if (typeof g.window !== "undefined" || typeof g.document !== "undefined") {
+    return { runtime: "browser" };
+  }
+  return { runtime: "unknown" };
+}
+function checkCompatibility() {
+  const warnings = [];
+  const { runtime, nodeVersion } = detectRuntime();
+  const cryptoAvailable = typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.getRandomValues === "function";
+  if (!cryptoAvailable) {
+    warnings.push(
+      "Web Crypto API (crypto.getRandomValues) is unavailable. Secure generation will fail. On Node.js, upgrade to v18 or newer."
+    );
+  }
+  if (runtime === "node" && nodeVersion) {
+    const major = parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+    if (major < MIN_NODE_VERSION) {
+      warnings.push(
+        `Node.js ${nodeVersion} is below the supported minimum (v${MIN_NODE_VERSION}). Please upgrade.`
+      );
+    }
+  }
+  return {
+    ok: cryptoAvailable && warnings.length === 0,
+    cryptoAvailable,
+    runtime,
+    ...nodeVersion ? { nodeVersion } : {},
+    warnings
+  };
+}
+function assertCompatible() {
+  const report = checkCompatibility();
+  if (!report.ok) {
+    throw new Error(`@ppabari/strio: incompatible runtime.
+- ${report.warnings.join("\n- ")}`);
+  }
+}
+
 // src/presets.ts
 var PRESETS = {
   /**
@@ -1876,6 +1924,6 @@ async function generateRandomStringAsync(options = {}) {
   return generateBatch(rest, count);
 }
 
-export { WORD_LIST as BUILT_IN_WORD_LIST, CHARSET_ALIASES, PRESETS, estimateEntropy, generateAesKey, generateApiKey, generateBase64Key, generateBytes, generateCookieSecret, generateDjangoSecretKey, generateExpiringToken, generateHexKey, generateId, generateJwtSecret, generateNextAuthSecret, generateOtp, generatePassphrase, generateRailsSecretKeyBase, generateRandomString, generateRandomStringAsync, maskSecret, randomStringSchema, randomStringStream, resolveCharsetAlias, take, takeWhere, timingSafeEqual, uniqueRandomStringStream, validateId, validateRandomString, verifyToken };
+export { WORD_LIST as BUILT_IN_WORD_LIST, CHARSET_ALIASES, MIN_NODE_VERSION, PRESETS, assertCompatible, checkCompatibility, estimateEntropy, generateAesKey, generateApiKey, generateBase64Key, generateBytes, generateCookieSecret, generateDjangoSecretKey, generateExpiringToken, generateHexKey, generateId, generateJwtSecret, generateNextAuthSecret, generateOtp, generatePassphrase, generateRailsSecretKeyBase, generateRandomString, generateRandomStringAsync, maskSecret, randomStringSchema, randomStringStream, resolveCharsetAlias, take, takeWhere, timingSafeEqual, uniqueRandomStringStream, validateId, validateRandomString, verifyToken };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map