@zerotal/client 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -8,6 +8,35 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+### Fixed
+
+- **The documented import could not be bundled for a browser.** `import { Socket } from
+  "@zerotal/client"` — the line the broadcasting guide taught — failed with `Browser build cannot
+  import() Bun builtin: "bun"`. The root entry also exports `ClientProvider`, which extends core's
+  `ServiceProvider`, which reaches `CommandRunner`, which reaches the built-in CLI commands, one of
+  which does `await import("bun")`. That is a *resolution*-time error, so tree-shaking never got the
+  chance to drop the half nobody in a browser wanted: one server-only export made the whole package
+  unusable in the environment it exists for.
+
+  `@zerotal/client` now resolves to a browser-safe entry under the `browser` export condition —
+  `Socket`, `ApiClient`, `CircuitBreaker`, `createApiClient` and their types, and none of the
+  server-side exports. Bun and Node consumers still get the full barrel, `ClientProvider` included,
+  so nothing about registering the package changes. `@zerotal/client/Socket` still works and is
+  still the leanest import when `Socket` is all you need; `ClientProvider` also gained an explicit
+  `./provider` subpath.
+
+  Two supporting changes: `createApiClient` moved out of `index.ts` into its own module, because a
+  browser entry re-exporting it from the barrel pulls the barrel back in — the first attempt at this
+  fix did exactly that and bundled straight back into the same error. And the modules a browser can
+  reach now import from narrow core subpaths (`@zerotal/core/errors`, `@zerotal/core/helpers`)
+  rather than the root, because importing *anything at all* from core's root is enough to poison a
+  browser bundle.
+
+  Guarded by a test that runs `Bun.build` with `target: "browser"` — no unit test can see this,
+  since every module imports fine under Bun — plus one that holds the browser entry in step with
+  the barrel, since two entry points means two places to remember to add an export to.
+
+
 ## [1.0.3] — 2026-08-07
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/client",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -8,8 +8,12 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./Socket": "./src/Socket.ts"
+    ".": {
+      "browser": "./src/browser.ts",
+      "default": "./src/index.ts"
+    },
+    "./Socket": "./src/Socket.ts",
+    "./provider": "./src/provider/ClientProvider.ts"
   },
   "files": [
     "CHANGELOG.md",
@@ -31,7 +35,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.0"
+    "@zerotal/core": "1.7.2"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/CircuitBreaker.ts

@@ -1,4 +1,4 @@
-import { ZerotalError } from "@zerotal/core";
+import { ZerotalError } from "@zerotal/core/errors";
 import { ApiClientError } from "./ApiClient.ts";
 
 // ── Types ─────────────────────────────────────────────────────────────────────

package/src/Socket.ts

@@ -4,7 +4,7 @@
 // broadcasting protocol (the `ws` / `redis` drivers) and exposes a familiar
 // realtime-client API — the same `channel()/private()/join()/leave()` +
 // `listen()/here()/joining()/leaving()` surface — so it works with `@zerotal/flow`'s
-// `@on('echo:…')` listeners with zero external dependencies.
+// `@on('socket:…')` listeners with zero external dependencies.
 //
 //   import { Socket } from "@zerotal/client";
 //
@@ -335,14 +335,14 @@ export class Socket {
     return this._subscribe(wire, () => new PresenceChannel(wire, this)) as PresenceChannel;
   }
 
-  /** Echo alias for {@link presence} (`window.Echo.join(...)`). */
+  /** Alias for {@link presence} (`window.Socket.join(...)`). */
   join(name: string): PresenceChannel {
     return this.presence(name);
   }
 
   /**
    * Leave a channel by its base name — unsubscribes the public, `private-`, and `presence-`
-   * variants (Echo's `leave()` semantics).
+   * variants, which is what `leave()` means here.
    */
   leave(name: string): void {
     this.leaveChannel(name);

package/src/browser.ts

@@ -0,0 +1,54 @@
+/**
+ * The browser-safe half of this package.
+ *
+ * Resolved for `import … from "@zerotal/client"` under the `browser` export
+ * condition, so a bundler targeting a browser gets this file and a Bun/Node
+ * import gets `index.ts` unchanged. Nobody has to know: the documented import
+ * is the same either way.
+ *
+ * What it leaves out is `ClientProvider` and `ClientConfig` — the two things
+ * here that are genuinely server-side. `ClientProvider` extends core's
+ * `ServiceProvider`, which reaches `CommandRunner`, which reaches the built-in
+ * CLI commands, one of which does `await import("bun")`. That is a hard error in
+ * a browser build and it happens during *resolution*, so tree-shaking never gets
+ * a chance to drop the unused half. The whole package became unbundleable
+ * because of one export nobody in a browser wanted.
+ *
+ * The rule this encodes: `@zerotal/core`'s root entry is server-only. A module
+ * that can run in a browser imports from a narrow subpath — `@zerotal/core/errors`,
+ * `@zerotal/core/helpers` — and never from the root.
+ */
+export type {
+  ApiRouteMap,
+  RouteShape,
+  HttpMethod,
+  PathParams,
+  ParamRecord,
+  PathsFor,
+  ResponseOf,
+  BodyOf,
+  QueryOf,
+} from "./types.ts";
+
+export { ApiClient, ApiClientError, ValidationError } from "./ApiClient.ts";
+export type {
+  ApiClientConfig,
+  RequestConfig,
+  RequestInterceptor,
+  ResponseContext,
+  ResponseInterceptor,
+  ResponseMeta,
+  RequestOptions,
+  GetOptions,
+  MutationOptions,
+  TokenSource,
+  RetryOptions,
+} from "./ApiClient.ts";
+
+export { CircuitBreaker, CircuitBreakerOpenError } from "./CircuitBreaker.ts";
+export type { CircuitBreakerOptions, CircuitState } from "./CircuitBreaker.ts";
+
+export { Socket, Channel, PresenceChannel } from "./Socket.ts";
+export type { SocketOptions, SocketState, SocketLike, PresenceMember } from "./Socket.ts";
+
+export { createApiClient } from "./createApiClient.ts";

package/src/config.ts

@@ -1,4 +1,4 @@
-import { deepMerge } from "@zerotal/core";
+import { deepMerge } from "@zerotal/core/helpers";
 import type { ApiClientConfig } from "./ApiClient.ts";
 
 export interface ClientConfigShape extends ApiClientConfig {

package/src/createApiClient.ts

@@ -0,0 +1,36 @@
+// ── Factory function ──────────────────────────────────────────────────────────
+//
+// Its own module rather than a member of `index.ts`, so the browser entry can
+// re-export it without pulling the server half of the barrel back in. That is
+// not hypothetical tidiness: `browser.ts` originally took it from `index.ts`,
+// which re-imported `ClientProvider` and put the bundle straight back into the
+// error this split exists to remove.
+
+import { ApiClient } from "./ApiClient.ts";
+import type { ApiRouteMap } from "./types.ts";
+import type { ApiClientConfig } from "./ApiClient.ts";
+
+/**
+ * Create a type-safe API client bound to your route map.
+ *
+ * @example
+ * // frontend/api.ts
+ * import { createApiClient } from '@zerotal/client';
+ * import type { Routes } from './routes';
+ *
+ * export const api = createApiClient<Routes>({
+ *   baseUrl: '/api',
+ *   headers: { 'X-Requested-With': 'XMLHttpRequest' },
+ * });
+ *
+ * // Anywhere in your UI:
+ * const user = await api.get('/users/{id}', { id: 1 });
+ * //    ^? UserResource  (inferred from Routes)
+ *
+ * const newUser = await api.post('/users', { name: 'Alice', email: 'alice@ex.com' });
+ */
+export function createApiClient<Routes extends ApiRouteMap>(
+  config: ApiClientConfig = {},
+): ApiClient<Routes> {
+  return new ApiClient<Routes>(config);
+}

package/src/errors.ts

@@ -1,4 +1,4 @@
-import { ZerotalError } from "@zerotal/core";
+import { ZerotalError } from "@zerotal/core/errors";
 
 /**
  * Thrown for any non-2xx HTTP response.

package/src/index.ts

@@ -36,33 +36,4 @@ export { ClientProvider, Client } from "./provider/ClientProvider.ts";
 export { ClientConfig } from "./config.ts";
 export type { ClientConfigShape } from "./config.ts";
 
-// ── Factory function ──────────────────────────────────────────────────────────
-
-import { ApiClient } from "./ApiClient.ts";
-import type { ApiRouteMap } from "./types.ts";
-import type { ApiClientConfig } from "./ApiClient.ts";
-
-/**
- * Create a type-safe API client bound to your route map.
- *
- * @example
- * // frontend/api.ts
- * import { createApiClient } from '@zerotal/client';
- * import type { Routes } from './routes';
- *
- * export const api = createApiClient<Routes>({
- *   baseUrl: '/api',
- *   headers: { 'X-Requested-With': 'XMLHttpRequest' },
- * });
- *
- * // Anywhere in your UI:
- * const user = await api.get('/users/{id}', { id: 1 });
- * //    ^? UserResource  (inferred from Routes)
- *
- * const newUser = await api.post('/users', { name: 'Alice', email: 'alice@ex.com' });
- */
-export function createApiClient<Routes extends ApiRouteMap>(
-  config: ApiClientConfig = {},
-): ApiClient<Routes> {
-  return new ApiClient<Routes>(config);
-}
+export { createApiClient } from "./createApiClient.ts";