@gambonny/valext 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Jonny Gamba 2025
+
+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,105 @@
+# valext
+
+> Minimal helper for extracting typed, validated values from Valibot schemas.
+
+<br />
+
+Cloudflare Workers, Hono, and other runtime environments benefit from **explicit contracts** and **clear validation flows**.
+But `valibot.safeParse()` gives you nested boilerplate, and parsing logic often gets duplicated or abstracted too deeply.
+
+`valext` embraces a simple idea:
+
+### ✨ Extract values with structure and intent, without hiding what matters.
+
+```ts
+  const result = extract(schema).from(unknownValue, issues => console.warn(issues))
+```
+
+---
+
+## Installation
+
+```bash
+  pnpm add @gambonny/valext
+```
+
+---
+
+## Why `valext`?
+
+---
+
+
+## Example in Hono
+
+```ts
+import { validator } from 'hono/validator'
+import { extract } from '@gambonny/valext'
+import { signupSchema } from './schemas'
+
+app.post(
+  '/signup',
+  validator('json', async (body, c) => {
+    const { success, output } = extract(signupSchema).from(body, issues =>
+      c.var.logger.warn('validation failed', { issues }),
+    )
+
+    return success ? output : c.text('Invalid input')
+  }),
+)
+```
+
+---
+
+## API
+
+### `extract(schema).from(input, onError?)`
+
+Returns:
+
+```ts
+{
+  success: true;
+  output: T;
+  issues: undefined;
+}
+```
+
+or:
+
+```ts
+{
+  success: false;
+  output: undefined;
+  issues: ValibotFlattenedIssues;
+}
+```
+
+---
+
+### `extract(schema).safe(input, onError?)`
+
+Exactly like `valibot.safeParse()`, but lets you pass a callback for flattened errors.
+
+---
+
+### `extract(schema).parse(input)`
+
+Exactly like `valibot.parse()`. Will throw if input is invalid.
+
+---
+
+## Design Notes
+
+- ✅ `valext` uses `valibot.safeParse()` under the hood.
+- ✅ Errors are **flattened** with `valibot.flatten().nested` for easy rendering/logging.
+- ✅ If you need raw nested issues, just use `valibot.safeParse()` directly —  you’re not locked in.
+
+> **Reminder:** `valext` is not an abstraction layer —  it’s a tool for making your intent clear at the point of use.
+
+---
+
+## License
+
+[MIT](./LICENSE)
+

package/dist/extract-BX7JgYbE.d.ts

@@ -0,0 +1,22 @@
+import * as v from "valibot";
+
+//#region src/extract.d.ts
+type TypedSchema = v.BaseSchema<any, any, v.BaseIssue<unknown>>;
+type OnValidationError = (issues: ReturnType<typeof v.flatten>["nested"]) => void;
+type ExtractResult<TSchema extends TypedSchema> = {
+  success: true;
+  output: v.InferOutput<TSchema>;
+  issues: undefined;
+} | {
+  success: false;
+  output: undefined;
+  issues: ReturnType<typeof v.flatten>["nested"];
+};
+declare function extract<TSchema extends TypedSchema>(schema: TSchema): {
+  from(input: unknown, onValidationError?: OnValidationError): ExtractResult<TSchema>;
+  safe(input: unknown, onValidationError?: OnValidationError): ReturnType<typeof v.safeParse>;
+  parse(input: unknown): v.InferOutput<TSchema>;
+};
+//#endregion
+export { ExtractResult, OnValidationError, extract };
+//# sourceMappingURL=extract-BX7JgYbE.d.ts.map

package/dist/extract-BX7JgYbE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-BX7JgYbE.d.ts","names":[],"sources":["../src/extract.ts"],"sourcesContent":[],"mappings":";;;KAGK,WAAA,GAAc,CAAA,CAAE,qBAAqB,CAAA,CAAE;KAGhC,iBAAA,YACF,kBAAkB,CAAA,CAAE;AAJzB,KAQO,aARI,CAAA,gBAQ0B,WAR1B,CAAA,GAAA;EAAA,OAAA,EAAA,IAAA;EAAA,MAA4B,EASf,CAAA,CAAE,WATa,CASD,OATC,CAAA;EAAS,MAAhC,EAAA,SAAA;AAAU,CAAA,GAAA;EAGnB,OAAA,EAAA,KAAA;EAAiB,MAAA,EAAA,SAAA;EAAA,MACC,EAShB,UATgB,CAAA,OASE,CAAA,CAAE,OATJ,CAAA,CAAA,QAAA,CAAA;CAAO;AAAjB,iBAaJ,OAbI,CAAA,gBAaoB,WAbpB,CAAA,CAAA,MAAA,EAayC,OAbzC,CAAA,EAAA;EAIR,IAAA,CAAA,KAAA,EAAA,OAAa,EAAA,iBAAA,CAAA,EAcC,iBAdD,CAAA,EAelB,aAfkB,CAeJ,OAfI,CAAA;EAAA,IAAA,CAAA,KAAA,EAAA,OAAA,EAAA,iBAAA,CAAA,EAoCC,iBApCD,CAAA,EAqClB,UArCkB,CAAA,OAqCA,CAAA,CAAE,SArCF,CAAA;EAAA,KAAiB,CAAA,KAAA,EAAA,OAAA,CAAA,EAgDf,CAAA,CAAE,WAhDa,CAgDD,OAhDC,CAAA;CAAW"}

package/dist/extract-COvJXyrv.js

@@ -0,0 +1,2 @@
+import*as e from"valibot";function t(t){return{from(n,r){let i=e.safeParse(t,n);if(i.success)return{success:!0,output:i.output,issues:void 0};let a=e.flatten(i.issues).nested;return r?.(a),{success:!1,output:void 0,issues:a}},safe(n,r){let i=e.safeParse(t,n);return i.success||r?.(e.flatten(i.issues).nested),i},parse(n){return e.parse(t,n)}}}export{t as extract};
+//# sourceMappingURL=extract-COvJXyrv.js.map

package/dist/extract-COvJXyrv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-COvJXyrv.js","names":["schema: TSchema","input: unknown","onValidationError?: OnValidationError"],"sources":["../src/extract.ts"],"sourcesContent":["import * as v from \"valibot\"\n\n// Base schema type used across all extract functions\ntype TypedSchema = v.BaseSchema<any, any, v.BaseIssue<unknown>>\n\n// Optional error handler used when validation fails\nexport type OnValidationError = (\n  issues: ReturnType<typeof v.flatten>[\"nested\"],\n) => void\n\n// Unified result shape for `from()` method\nexport type ExtractResult<TSchema extends TypedSchema> =\n  | { success: true; output: v.InferOutput<TSchema>; issues: undefined }\n  | {\n      success: false\n      output: undefined\n      issues: ReturnType<typeof v.flatten>[\"nested\"]\n    }\n\n// Factory function to wrap Valibot schema with safe utilities\nexport function extract<TSchema extends TypedSchema>(schema: TSchema) {\n  return {\n    // Runs safeParse() and returns a normalized result shape\n    from(\n      input: unknown,\n      onValidationError?: OnValidationError,\n    ): ExtractResult<TSchema> {\n      const result = v.safeParse(schema, input)\n\n      if (result.success) {\n        return { success: true, output: result.output, issues: undefined }\n      }\n\n      // Flatten issues for cleaner consumption\n      const flattened = v.flatten(result.issues).nested\n      onValidationError?.(flattened)\n\n      return {\n        success: false,\n        output: undefined,\n        issues: flattened,\n      }\n    },\n\n    // Same as Valibot's safeParse, but optionally hooks into error handling\n    safe(\n      input: unknown,\n      onValidationError?: OnValidationError,\n    ): ReturnType<typeof v.safeParse> {\n      const result = v.safeParse(schema, input)\n\n      if (!result.success) {\n        onValidationError?.(v.flatten(result.issues).nested)\n      }\n\n      return result\n    },\n\n    // Raw parse that throws on failure — same as Valibot’s parse\n    parse(input: unknown): v.InferOutput<TSchema> {\n      return v.parse(schema, input)\n    },\n  }\n}\n"],"mappings":"0BAoBA,SAAgB,EAAqCA,EAAiB,CACpE,MAAO,CAEL,KACEC,EACAC,EACwB,CACxB,IAAM,EAAS,EAAE,UAAU,EAAQ,EAAM,CAEzC,GAAI,EAAO,QACT,MAAO,CAAE,QAAS,GAAM,OAAQ,EAAO,OAAQ,OAAQ,IAAA,EAAW,EAIpE,IAAM,EAAY,EAAE,QAAQ,EAAO,OAAO,CAAC,OAG3C,OAFA,IAAoB,EAAU,CAEvB,CACL,QAAS,GACT,OAAQ,IAAA,GACR,OAAQ,CACT,CACF,EAGD,KACED,EACAC,EACgC,CAChC,IAAM,EAAS,EAAE,UAAU,EAAQ,EAAM,CAMzC,OAJK,EAAO,SACV,IAAoB,EAAE,QAAQ,EAAO,OAAO,CAAC,OAAO,CAG/C,CACR,EAGD,MAAMD,EAAwC,CAC5C,OAAO,EAAE,MAAM,EAAQ,EAAM,AAC9B,CACF,CACF"}

package/dist/extract.d.ts

@@ -0,0 +1,2 @@
+import { ExtractResult, OnValidationError, extract } from "./extract-BX7JgYbE.js";
+export { ExtractResult, OnValidationError, extract };

package/dist/extract.js

@@ -0,0 +1 @@
+import{extract as e}from"./extract-COvJXyrv.js";export{e as extract};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { ExtractResult, OnValidationError, extract } from "./extract-BX7JgYbE.js";
+export { type ExtractResult, type OnValidationError, extract };

package/dist/index.js

@@ -0,0 +1 @@
+import{extract as e}from"./extract-COvJXyrv.js";export{e as extract};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@gambonny/valext",
+  "author": "Jonny Gamba",
+  "version": "0.1.0",
+  "sideEffects": true,
+  "description": "Minimal extraction and validation helper for Valibot.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "format": "pnpm exec biome format --write",
+    "lint": "pnpm exec biome lint",
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest"
+  },
+  "keywords": [
+    "valibot",
+    "extract",
+    "fluent-api",
+    "runtime-validation"
+  ],
+  "license": "ISC",
+  "packageManager": "pnpm@10.13.1",
+  "devDependencies": {
+    "@biomejs/biome": "2.1.2",
+    "lefthook": "^1.12.2",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3",
+    "valibot": "^1.1.0",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "valibot": "^1.1.0"
+  },
+  "files": [
+    "dist"
+  ]
+}