snapenv 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Visible
+
+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/dist/index.cjs

@@ -0,0 +1,3 @@
+"use strict";var v=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var x=Object.prototype.hasOwnProperty;var h=(n,r)=>{for(var t in r)v(n,t,{get:r[t],enumerable:!0})},E=(n,r,t,i)=>{if(r&&typeof r=="object"||typeof r=="function")for(let s of p(r))!x.call(n,s)&&s!==t&&v(n,s,{get:()=>r[s],enumerable:!(i=T(r,s))||i.enumerable});return n};var $=n=>E(v({},"__esModule",{value:!0}),n);var j={};h(j,{createSnap:()=>I,snap:()=>b,validate:()=>R});module.exports=$(j);var m={email:/^[^\s@]+@[^\s@]+\.[^\s@]+$/,uuid:/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,host:/^(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}|localhost|\d{1,3}(?:\.\d{1,3}){3})$/i},y=/secret|password|token|key|api|auth|credential|private/i;function N(n){if(n.includes("=")){let s=n.indexOf("="),d=n.slice(0,s),f=n.slice(s+1);return{base:d.endsWith("!")?d.slice(0,-1):d,required:!0,defaultValue:f}}let t=n.endsWith("!");return{base:t?n.slice(0,-1):n,required:t,defaultValue:void 0}}function o(n,r,t){return t?y.test(r)?'"[MASKED]"':`"${n}"`:`"${n}"`}function B(n,r,t,i,s){if(Array.isArray(r))return n===void 0||i&&n===""?{value:void 0,error:`required, must be one of: ${r.join(", ")}`}:r.includes(n)?{value:n}:{value:void 0,error:`must be one of: ${r.join(", ")}, got ${o(n,t,s)}`};let{base:d,required:f,defaultValue:a}=N(r),e=n;if((e===void 0||i&&e==="")&&a!==void 0&&(e=a),e===void 0||i&&e==="")return f?{value:void 0,error:"required but not set"}:{value:void 0};switch(d){case"string":return{value:e};case"number":{let u=Number(e);return isNaN(u)?{value:void 0,error:`must be a number, got ${o(e,t,s)}`}:{value:u}}case"integer":{let u=Number(e);return isNaN(u)||!Number.isInteger(u)?{value:void 0,error:`must be an integer, got ${o(e,t,s)}`}:{value:u}}case"port":{let u=Number(e);return isNaN(u)||!Number.isInteger(u)||u<1||u>65535?{value:void 0,error:`must be a valid port (1-65535), got ${o(e,t,s)}`}:{value:u}}case"boolean":{let u=e.toLowerCase();return["true","1","yes","on"].includes(u)?{value:!0}:["false","0","no","off"].includes(u)?{value:!1}:{value:void 0,error:`must be a boolean, got ${o(e,t,s)}`}}case"url":try{return new URL(e),{value:e}}catch{return{value:void 0,error:`must be a valid URL, got ${o(e,t,s)}`}}case"email":return m.email.test(e)?{value:e}:{value:void 0,error:`must be a valid email, got ${o(e,t,s)}`};case"host":return m.host.test(e)?{value:e}:{value:void 0,error:`must be a valid host, got ${o(e,t,s)}`};case"uuid":return m.uuid.test(e)?{value:e}:{value:void 0,error:`must be a valid UUID, got ${o(e,t,s)}`};case"json":try{return{value:JSON.parse(e)}}catch{return{value:void 0,error:`must be valid JSON, got ${o(e,t,s)}`}}case"string[]":return{value:e.split(",").map(l=>l.trim())};case"number[]":{let u=e.split(",").map(c=>c.trim()),l=[];for(let c of u){let g=Number(c);if(isNaN(g))return{value:void 0,error:`must be comma-separated numbers, got ${o(e,t,s)}`};l.push(g)}return{value:l}}default:return{value:e}}}function O(){return typeof process<"u"&&process.env?process.env:typeof Deno<"u"&&Deno?Deno.env.toObject():{}}function b(n,r={}){let t=r.source??O(),i=r.emptyAsUndefined??!0,s=r.maskSecrets??!1,d=r.prefix??"",f={},a=[];for(let[e,u]of Object.entries(n)){let l=d+e,{value:c,error:g}=B(t[l],u,e,i,s);g?a.push(`${l}: ${g}`):f[e]=c}if(a.length>0){let e=`snapenv validation failed:
+  ${a.join(`
+  `)}`;if(r.onError==="log")console.error(e);else if(typeof r.onError=="function")r.onError(a);else throw new Error(e)}return Object.freeze(f)}function I(n){return(r,t={})=>b(r,{...n,...t})}function R(n,r={}){let t=[],i=b(n,{...r,onError:s=>t.push(...s)});return t.length>0?{success:!1,errors:t}:{success:!0,data:i}}0&&(module.exports={createSnap,snap,validate});

package/dist/index.d.cts

@@ -0,0 +1,32 @@
+type BaseType = "string" | "string!" | "number" | "number!" | "integer" | "integer!" | "port" | "port!" | "boolean" | "boolean!" | "url" | "url!" | "email" | "email!" | "host" | "host!" | "uuid" | "uuid!" | "json" | "json!" | "string[]" | "string[]!" | "number[]" | "number[]!";
+type WithDefault<T extends string> = `${T}=${string}`;
+type EnvType = BaseType | WithDefault<BaseType> | readonly string[];
+type EnvSchema = Record<string, EnvType>;
+type IsRequired<T extends string> = T extends `${infer Base}!${string}` ? true : T extends `${string}=${string}` ? true : false;
+type ExtractBase<T extends string> = T extends `${infer Base}!` ? Base : T extends `${infer Base}=${string}` ? ExtractBase<Base> : T;
+type BaseToType<T extends string> = T extends "string" | "string!" ? string : T extends "number" | "number!" | "integer" | "integer!" | "port" | "port!" ? number : T extends "boolean" | "boolean!" ? boolean : T extends "url" | "url!" | "email" | "email!" | "host" | "host!" | "uuid" | "uuid!" ? string : T extends "json" | "json!" ? unknown : T extends "string[]" | "string[]!" ? string[] : T extends "number[]" | "number[]!" ? number[] : string;
+type InferType<T extends EnvType> = T extends readonly string[] ? T[number] : T extends string ? IsRequired<T> extends true ? BaseToType<ExtractBase<T>> : BaseToType<ExtractBase<T>> | undefined : never;
+type InferEnv<T extends EnvSchema> = {
+    readonly [K in keyof T]: InferType<T[K]>;
+};
+type Options = {
+    source?: Record<string, string | undefined>;
+    prefix?: string;
+    onError?: "throw" | "log" | ((errors: string[]) => void);
+    emptyAsUndefined?: boolean;
+    maskSecrets?: boolean;
+};
+declare function snap<T extends EnvSchema>(schema: T, options?: Options): InferEnv<T>;
+declare function createSnap(defaultOptions: Options): <T extends EnvSchema>(schema: T, options?: Options) => InferEnv<T>;
+type ValidateResult<T extends EnvSchema> = {
+    success: true;
+    data: InferEnv<T>;
+    errors: never;
+} | {
+    success: false;
+    data: never;
+    errors: string[];
+};
+declare function validate<T extends EnvSchema>(schema: T, options?: Omit<Options, "onError">): ValidateResult<T>;
+
+export { type EnvSchema, type EnvType, type InferEnv, type Options, createSnap, snap, validate };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+type BaseType = "string" | "string!" | "number" | "number!" | "integer" | "integer!" | "port" | "port!" | "boolean" | "boolean!" | "url" | "url!" | "email" | "email!" | "host" | "host!" | "uuid" | "uuid!" | "json" | "json!" | "string[]" | "string[]!" | "number[]" | "number[]!";
+type WithDefault<T extends string> = `${T}=${string}`;
+type EnvType = BaseType | WithDefault<BaseType> | readonly string[];
+type EnvSchema = Record<string, EnvType>;
+type IsRequired<T extends string> = T extends `${infer Base}!${string}` ? true : T extends `${string}=${string}` ? true : false;
+type ExtractBase<T extends string> = T extends `${infer Base}!` ? Base : T extends `${infer Base}=${string}` ? ExtractBase<Base> : T;
+type BaseToType<T extends string> = T extends "string" | "string!" ? string : T extends "number" | "number!" | "integer" | "integer!" | "port" | "port!" ? number : T extends "boolean" | "boolean!" ? boolean : T extends "url" | "url!" | "email" | "email!" | "host" | "host!" | "uuid" | "uuid!" ? string : T extends "json" | "json!" ? unknown : T extends "string[]" | "string[]!" ? string[] : T extends "number[]" | "number[]!" ? number[] : string;
+type InferType<T extends EnvType> = T extends readonly string[] ? T[number] : T extends string ? IsRequired<T> extends true ? BaseToType<ExtractBase<T>> : BaseToType<ExtractBase<T>> | undefined : never;
+type InferEnv<T extends EnvSchema> = {
+    readonly [K in keyof T]: InferType<T[K]>;
+};
+type Options = {
+    source?: Record<string, string | undefined>;
+    prefix?: string;
+    onError?: "throw" | "log" | ((errors: string[]) => void);
+    emptyAsUndefined?: boolean;
+    maskSecrets?: boolean;
+};
+declare function snap<T extends EnvSchema>(schema: T, options?: Options): InferEnv<T>;
+declare function createSnap(defaultOptions: Options): <T extends EnvSchema>(schema: T, options?: Options) => InferEnv<T>;
+type ValidateResult<T extends EnvSchema> = {
+    success: true;
+    data: InferEnv<T>;
+    errors: never;
+} | {
+    success: false;
+    data: never;
+    errors: string[];
+};
+declare function validate<T extends EnvSchema>(schema: T, options?: Omit<Options, "onError">): ValidateResult<T>;
+
+export { type EnvSchema, type EnvType, type InferEnv, type Options, createSnap, snap, validate };

package/dist/index.js

@@ -0,0 +1,3 @@
+var v={email:/^[^\s@]+@[^\s@]+\.[^\s@]+$/,uuid:/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,host:/^(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}|localhost|\d{1,3}(?:\.\d{1,3}){3})$/i},b=/secret|password|token|key|api|auth|credential|private/i;function T(r){if(r.includes("=")){let u=r.indexOf("="),d=r.slice(0,u),f=r.slice(u+1);return{base:d.endsWith("!")?d.slice(0,-1):d,required:!0,defaultValue:f}}let n=r.endsWith("!");return{base:n?r.slice(0,-1):r,required:n,defaultValue:void 0}}function i(r,t,n){return n?b.test(t)?'"[MASKED]"':`"${r}"`:`"${r}"`}function p(r,t,n,o,u){if(Array.isArray(t))return r===void 0||o&&r===""?{value:void 0,error:`required, must be one of: ${t.join(", ")}`}:t.includes(r)?{value:r}:{value:void 0,error:`must be one of: ${t.join(", ")}, got ${i(r,n,u)}`};let{base:d,required:f,defaultValue:a}=T(t),e=r;if((e===void 0||o&&e==="")&&a!==void 0&&(e=a),e===void 0||o&&e==="")return f?{value:void 0,error:"required but not set"}:{value:void 0};switch(d){case"string":return{value:e};case"number":{let s=Number(e);return isNaN(s)?{value:void 0,error:`must be a number, got ${i(e,n,u)}`}:{value:s}}case"integer":{let s=Number(e);return isNaN(s)||!Number.isInteger(s)?{value:void 0,error:`must be an integer, got ${i(e,n,u)}`}:{value:s}}case"port":{let s=Number(e);return isNaN(s)||!Number.isInteger(s)||s<1||s>65535?{value:void 0,error:`must be a valid port (1-65535), got ${i(e,n,u)}`}:{value:s}}case"boolean":{let s=e.toLowerCase();return["true","1","yes","on"].includes(s)?{value:!0}:["false","0","no","off"].includes(s)?{value:!1}:{value:void 0,error:`must be a boolean, got ${i(e,n,u)}`}}case"url":try{return new URL(e),{value:e}}catch{return{value:void 0,error:`must be a valid URL, got ${i(e,n,u)}`}}case"email":return v.email.test(e)?{value:e}:{value:void 0,error:`must be a valid email, got ${i(e,n,u)}`};case"host":return v.host.test(e)?{value:e}:{value:void 0,error:`must be a valid host, got ${i(e,n,u)}`};case"uuid":return v.uuid.test(e)?{value:e}:{value:void 0,error:`must be a valid UUID, got ${i(e,n,u)}`};case"json":try{return{value:JSON.parse(e)}}catch{return{value:void 0,error:`must be valid JSON, got ${i(e,n,u)}`}}case"string[]":return{value:e.split(",").map(l=>l.trim())};case"number[]":{let s=e.split(",").map(c=>c.trim()),l=[];for(let c of s){let g=Number(c);if(isNaN(g))return{value:void 0,error:`must be comma-separated numbers, got ${i(e,n,u)}`};l.push(g)}return{value:l}}default:return{value:e}}}function x(){return typeof process<"u"&&process.env?process.env:typeof Deno<"u"&&Deno?Deno.env.toObject():{}}function m(r,t={}){let n=t.source??x(),o=t.emptyAsUndefined??!0,u=t.maskSecrets??!1,d=t.prefix??"",f={},a=[];for(let[e,s]of Object.entries(r)){let l=d+e,{value:c,error:g}=p(n[l],s,e,o,u);g?a.push(`${l}: ${g}`):f[e]=c}if(a.length>0){let e=`snapenv validation failed:
+  ${a.join(`
+  `)}`;if(t.onError==="log")console.error(e);else if(typeof t.onError=="function")t.onError(a);else throw new Error(e)}return Object.freeze(f)}function h(r){return(t,n={})=>m(t,{...r,...n})}function E(r,t={}){let n=[],o=m(r,{...t,onError:u=>n.push(...u)});return n.length>0?{success:!1,errors:n}:{success:!0,data:o}}export{h as createSnap,m as snap,E as validate};

package/package.json

@@ -1,12 +1,55 @@
 {
   "name": "snapenv",
-  "version": "0.0.0",
-  "description": "Reserved package name",
-  "main": "index.js",
+  "version": "0.1.0",
+  "description": "typesafe env validation with zero dependencies",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "env",
+    "environment",
+    "variables",
+    "validation",
+    "typescript",
+    "types",
+    "dotenv",
+    "config",
+    "typesafe",
+    "schema",
+    "parse",
+    "process.env"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Visible",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/visible/snapenv"
   },
-  "keywords": ["placeholder", "reserved"],
-  "author": "josh",
-  "license": "MIT"
-}
+  "homepage": "https://github.com/visible/snapenv",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,115 @@
+```
+┌──────────────────────────────────────────────────────────────┐
+│                                                              │
+│   ◇  snapenv                                                 │
+│                                                              │
+│   typesafe env validation with zero dependencies             │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+```bash
+> what is this?
+
+  a tiny library that validates and types your environment variables
+  no zod, no dependencies, just one function
+
+> example?
+
+  const env = snap({
+    DATABASE_URL: "url!",
+    PORT: "port=3000",
+    DEBUG: "boolean=false",
+    NODE_ENV: ["development", "production", "test"],
+    ALLOWED_IPS: "string[]",
+  })
+
+  env.PORT        // number (3000 if not set)
+  env.DEBUG       // boolean (false if not set)
+  env.NODE_ENV    // "development" | "production" | "test"
+  env.ALLOWED_IPS // string[]
+
+> features?
+
+  ✓ zero dependencies
+  ✓ full typescript inference
+  ✓ runtime parsing (actual numbers, booleans, arrays)
+  ✓ default values
+  ✓ prefix support (NEXT_PUBLIC_, VITE_)
+  ✓ secret masking in errors
+  ✓ works everywhere (node, deno, bun, edge)
+
+> types?
+
+  string      any string              string | undefined
+  string!     required string         string
+  number      parsed number           number | undefined
+  integer     whole number only       number | undefined
+  port        valid port 1-65535      number | undefined
+  boolean     true/false, 1/0, yes/no boolean | undefined
+  url         valid url               string | undefined
+  email       valid email             string | undefined
+  host        hostname or ip          string | undefined
+  uuid        valid uuid              string | undefined
+  json        parsed json             unknown
+  string[]    comma-separated         string[] | undefined
+  number[]    comma-separated numbers number[] | undefined
+  [...]       enum of values          union type
+
+  add ! to make required: number!, url!, email!
+  add =value for defaults: port=3000, boolean=false
+
+> options?
+
+  snap(schema, {
+    source: process.env,       // custom env source
+    prefix: "NEXT_PUBLIC_",    // env var prefix
+    emptyAsUndefined: true,    // treat "" as undefined
+    maskSecrets: true,         // hide secrets in errors
+    onError: "throw",          // "throw" | "log" | (errors) => void
+  })
+
+> validate without throwing?
+
+  const result = validate(schema, options)
+
+  if (result.success) {
+    console.log(result.data.PORT)
+  } else {
+    console.log(result.errors)
+  }
+
+> prefix example?
+
+  // reads NEXT_PUBLIC_API_URL from env
+  const env = snap(
+    { API_URL: "url!" },
+    { prefix: "NEXT_PUBLIC_" }
+  )
+
+  env.API_URL // typed without prefix
+
+> createSnap?
+
+  const snap = createSnap({ prefix: "MY_APP_" })
+  const env = snap({ ... })
+
+> .env files?
+
+  snapenv validates, it doesn't load
+  use your runtime's native .env support:
+
+  bun app.ts                        # bun auto-loads .env
+  node --env-file=.env app.js       # node 20.6+
+  deno run --env-file=.env app.ts   # deno
+  node -r dotenv/config app.js      # older node
+
+> install?
+
+  bun add snapenv
+  npm install snapenv
+
+> license?
+
+  mit
+```

package/index.js

@@ -1,3 +0,0 @@
-export default function() {
-  console.log('This package is reserved');
-}