refactor: Download+url types (#93)

Author: kasperrt

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Releases
 
 ## Contents
+- [v0.3.3-alpha.1](#v0-3-3-alpha-1)
 - [v0.3.3-alpha.0](#v0-3-3-alpha-0)
 - [v0.3.2](#v0-3-2)
 - [v0.3.1](#v0-3-1)
@@ -16,6 +17,18 @@
 - [v0.1.0](#v0-1-0)
 - [v0.0.8](#v0-0-8)
 
+## v0.3.3-alpha.1
+
+- Make response optional for both `url` and `download`, but at the same time enforce `string` for `url`, and `Blob` for download if defined.
+- Add validation before `url` and `download` return.
+- Add more and better examples to guide for download + url.
+- Internal; Improve default destructuring in RequestClient.
+- Internal; More direct cache-pending return.
+- Internal; Cleanup pending cache faster.
+- Internal; More iteratively merging headers for nicer readability and sanitization.
+- Internal; Add AbortSignal.any execution attempt.
+- Internal; Reduce excessive checks and variables in validator function.
+
 ## v0.3.3-alpha.0
 
 - Bump @standard-schema/spec@1.1.0.

README.md

@@ -15,6 +15,8 @@
 [![minzip](https://deno.bundlejs.com/badge?q=wiretyped@latest)](https://bundlejs.com/?q=wiretyped@latest)
 
 
+[![npm](https://img.shields.io/npm/v/wiretyped.svg)](https://www.npmjs.com/package/wiretyped) [![JSR](https://jsr.io/badges/@kasperrt/wiretyped)](https://jsr.io/@kasperrt/wiretyped)
+
 Universal fetch-based, typed HTTP client with error-first ergonomics, retries, caching, SSE, and Standard Schema validation.
 
 https://wiretyped.io

docs/.vitepress/theme/style.css

@@ -144,45 +144,12 @@
   display: none;
 }
 
-.wt-hero-badges-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  justify-content: center;
-}
-
-@media (min-width: 960px) {
-  .wt-hero-badges-row {
-    justify-content: flex-start;
-  }
-}
-
-.wt-hero-badges-wrap {
-  text-align: left;
-  line-height: 12px;
-}
-
 /* Default theme centers hero text on small screens when a hero image exists.
    Keep this site left-aligned across breakpoints. */
 .VPHero.has-image .container {
   text-align: left;
 }
 
-.wt-hero-badge {
-  display: inline-flex;
-  line-height: 0;
-}
-
-.wt-hero-badge img {
-  height: 20px;
-  border-radius: 0;
-  opacity: 0.95;
-  transition:
-    opacity 140ms ease,
-    transform 140ms ease;
-}
-
-.wt-hero-badge:hover img {
-  opacity: 1;
-  transform: translateY(-1px);
+.vp-doc a {
+  display: inline-block;
 }

docs/guide/endpoints.md

@@ -164,9 +164,15 @@ export const exampleEndpoints = {
       response: z.instanceof(Blob),
     },
   },
-  '/links': {
+  '/authorization/{provider}': {
     url: {
-      response: z.string().url(),
+      $search: z.object({
+        popup: z.boolean(),
+      }).optional(),
+      $path: z.object({
+        provider: z.enum(['microsoft', 'google']),
+      }),
+      response: z.url(),
     },
   },
   '/events': {

docs/guide/methods.md

@@ -150,25 +150,40 @@ const [err, deletion] = await client.delete('/users/{id}', { id: '123' });
 
 ### DOWNLOAD
 
-`download` performs an HTTP `GET` request under the hood, but handles the response as binary and returns a `Blob` instance (it uses `response.blob()` internally instead of JSON parsing).
+`download` performs an HTTP `GET` request under the hood, but handles the response as binary and returns a `Blob` instance (it uses `response.blob()` internally instead of JSON parsing). `response` is optional and only accepts Blob.
 
 ```ts
 const endpoints = {
+  // Response not strictly needed, but only accepts Blob instances
   '/files/{id}/download': {
     download: { response: z.instanceof(Blob) },
   },
+  '/files/{id}/download/{type}': {
+    download: { $path: z.object({ type: z.enum(['pdf', 'png']) }) },
+  },
 } satisfies RequestDefinitions;
 
 const [err, file] = await client.download('/files/{id}/download', { id: 'file-1' });
 ```
 
 ### URL
 
+Structured similarly to other operations, but `response` is optional and only accepts strings.
+
 ```ts
 const endpoints = {
-  '/links': { url: { response: z.string().url() } },
+  // Response not strictly needed, but only accepts string derivatives
+  '/links': { 
+    url: { response: z.url() }
+  },
+  '/links/{integration}': { 
+    url: { 
+      $path: z.object({ integration: z.enum(['slack', 'github']) }) 
+    } 
+  },
 } satisfies RequestDefinitions;
 
+
 const [err, link] = await client.url('/links', null);
 ```
 
@@ -178,7 +193,7 @@ Use `url()` when you want a validated, parsed URL without making a request, e.g.
 
 #### Why async?
 
-`url()` generates a URL from the endpoint template + params and validates/parses the final result using the endpoint’s `url.response` schema. The “response” schema here is simply used to express that the return type is a string (and lets you attach extra validation like `z.string().url()`).
+`url()` generates a URL from the endpoint template + params and validates/parses the final result using the endpoint’s `url.response` schema. The “response” schema here is simply used to express that the return type is a string (and lets you attach extra validation like `z.url()`).
 
 It’s async because Standard Schema validators can be async, so the API is async even though it doesn’t hit the network.
 

docs/index.md

@@ -6,30 +6,6 @@ hero:
   name: WireTyped
   text: Typed HTTP client for fetch runtimes
   tagline: Universal fetch-based, typed HTTP client with error-first ergonomics, retries, caching, SSE, and Standard Schema validation.
-
-    <!-- All this to avoid a vue direct package -->
-    <!-- But at least you read this, so that's fun -->
-    <div class="wt-hero-badges-wrap">
-      <div class="wt-hero-badges-row">
-        <a class="wt-hero-badge" href="https://github.com/kasperrt/wiretyped/actions/workflows/ci.yml" target="_blank" rel="noreferrer">
-          <img src="https://github.com/kasperrt/wiretyped/actions/workflows/ci.yml/badge.svg" alt="CI" loading="lazy" decoding="async" />
-        </a>
-        <a class="wt-hero-badge" href="https://codecov.io/gh/kasperrt/wiretyped" target="_blank" rel="noreferrer">
-          <img src="https://codecov.io/gh/kasperrt/wiretyped/branch/main/graph/badge.svg" alt="Coverage" loading="lazy" decoding="async" />
-        </a>
-        <a class="wt-hero-badge" href="https://bundlejs.com/?q=wiretyped@latest" target="_blank" rel="noreferrer">
-          <img src="https://deno.bundlejs.com/badge?q=wiretyped@latest" alt="minzip" loading="lazy" decoding="async" />
-        </a>
-      </div>
-      <div class="wt-hero-badges-row">
-        <a class="wt-hero-badge" href="https://www.npmjs.com/package/wiretyped" target="_blank" rel="noreferrer">
-          <img src="https://img.shields.io/npm/v/wiretyped.svg" alt="npm" loading="lazy" decoding="async" />
-        </a>
-        <a class="wt-hero-badge" href="https://jsr.io/@kasperrt/wiretyped" target="_blank" rel="noreferrer">
-          <img src="https://jsr.io/badges/@kasperrt/wiretyped" alt="JSR" loading="lazy" decoding="async">
-        </a>
-      </div>
-    </div>
 
   actions:
     - theme: brand
@@ -60,13 +36,20 @@ features:
 
 ## What is it?
 
+> Small and easy-to-use fetch based client with runtime validation
+
+
+[![CI](https://github.com/kasperrt/wiretyped/actions/workflows/ci.yml/badge.svg)](https://github.com/kasperrt/wiretyped/actions/workflows/ci.yml) &nbsp; [![Coverage](https://codecov.io/gh/kasperrt/wiretyped/branch/main/graph/badge.svg)](https://codecov.io/gh/kasperrt/wiretyped) &nbsp; [![minzip](https://deno.bundlejs.com/badge?q=wiretyped@latest)](https://bundlejs.com/?q=wiretyped@latest)
+
+[![npm](https://img.shields.io/npm/v/wiretyped.svg)](https://www.npmjs.com/package/wiretyped) &nbsp; [![JSR](https://jsr.io/badges/@kasperrt/wiretyped)](https://jsr.io/@kasperrt/wiretyped)
+
 WireTyped is a small, composable HTTP client for fetch-based runtimes (browser, Node, Bun, Deno, workers). You define your API as typed endpoint definitions and call it with a consistent, error-first API.
 
-It has a tiny runtime surface area: one dependency, `@standard-schema/spec`, so you can bring your own validator (Zod, Valibot, ArkType, etc.) without dragging in a whole framework or a pile of transitive deps.
+It keeps a tiny runtime surface area: one dependency, `@standard-schema/spec`, so you can bring your own validator (Zod, Valibot, ArkType, etc.) without dragging in a whole framework or a pile of transitive deps. 
 
 I built it because I got tired of the same three problems: surprise runtime errors, wrapping every request in `try/catch`, and threading schemas + type inference through every call just to keep types strict and consistent. WireTyped centralizes that work in your endpoint definitions, so using the client stays predictable and pretty.
 
-## Quick example
+## Basic example
 
 Define your endpoints once, then call them with a consistent `[err, data]` shape with convenient type-narrowing:
 
@@ -96,6 +79,4 @@ console.log(user.name);
 
 ## Okay, wow
 
-This is the part where you pause for a second and go: okay, yeah. This is kinda beautiful. Let’s keep going.
-
-I got you: [`/guide/getting-started`](/guide/getting-started)
+If you’re nodding along and want to keep moving, jump into the quickstart: [`/guide/getting-started`](/guide/getting-started)

jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@kasperrt/wiretyped",
-  "version": "0.3.3-alpha.0",
+  "version": "0.3.3-alpha.1",
   "exports": {
     ".": "./src/index.ts"
   },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiretyped",
-  "version": "0.3.3-alpha.0",
+  "version": "0.3.3-alpha.1",
   "description": "Universal fetch-based HTTP client with robust error handling, retries, caching, SSE, and Standard Schema validation.",
   "type": "module",
   "keywords": [

pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - esbuild
+  - sharp
+  - workerd

src/cache/client.ts

@@ -80,8 +80,7 @@ export class CacheClient {
    * @param {Object} data - cache data
    */
   #add<T = unknown>(key: string, data: T, ttl: number) {
-    const expires = Date.now() + ttl;
-    this.#cache.set(key, { key, data, expires });
+    this.#cache.set(key, { key, data, expires: Date.now() + ttl });
   }
 
   /**
@@ -124,10 +123,12 @@ export class CacheClient {
       }
 
       this.#add(key, data, ttl);
+      this.#pending.delete(key);
       return [null, data];
     })();
 
     this.#pending.set(key, pending);
+    return pending;
   };
 
   /**
@@ -150,8 +151,7 @@ export class CacheClient {
       return pending as SafeWrapAsync<Error, T>;
     }
 
-    this.#addPendingRequest(key, res, ttl);
-    return this.#pending.get(key) as SafeWrapAsync<Error, T>;
+    return this.#addPendingRequest(key, res, ttl);
   };
 
   /**