@b3-business/cherry 0.3.1 → 0.3.2

package/README.md

@@ -10,9 +10,9 @@ A tree-shakeable, minimal API client factory. Import only the routes you need
 
 ---
 
-## Latest Changelog - 0.3.1
+## Latest Changelog - 0.3.2
 
-- Fix: Add `@types/bun` to monorepo root for editor TypeScript support
+- Fix: Ship TypeScript source files in npm package to fix module resolution
 
 See [CHANGELOG.md](https://github.com/b3-business/cherry/blob/main/packages/cherry/CHANGELOG.md) for full history.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b3-business/cherry",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "A tree-shakeable, minimal API client factory. Import only the routes you need — nothing more.",
   "repository": {
     "type": "git",
@@ -14,12 +14,12 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "scripts": {
     "build": "tsdown",
-    "check": "run-s lint typecheck",
-    "lint": "oxlint src test",
+    "check": "oxlint --type-aware --type-check src test",
     "typecheck": "tsc --noEmit -p .",
     "test": "bun test",
     "prepublishOnly": "npm run check && npm run test && npm run build",
@@ -34,8 +34,6 @@
     "@types/bun": "^1.3.5",
     "expect-type": "^1.3.0",
     "jsr": "^0.13.5",
-    "npm-run-all": "^4.1.5",
-    "oxlint": "^1.36.0",
     "tsdown": "^0.19.0-beta.2",
     "typescript": "^5.9.3"
   },

package/src/cherry_client.ts

@@ -0,0 +1,172 @@
+import { ResultAsync } from "neverthrow";
+import * as v from "valibot";
+import type {
+  CherryRoute,
+  CherryResult,
+  InferRouteInput,
+  InferRouteOutput,
+  Fetcher,
+  FetchRequest,
+  ClientConfig,
+  Client,
+  RouteTree,
+  RoutesToClient,
+  QueryParamOptions,
+} from "./types";
+import { HttpError, ValidationError, NetworkError, SerializationError, UnknownCherryError } from "./errors";
+
+const defaultFetcher: Fetcher = (req) => fetch(req.url, req.init);
+
+export function serializeQueryParams(
+  params: Record<string, unknown>,
+  options?: QueryParamOptions,
+): string {
+  if (options?.customSerializer) {
+    return options.customSerializer(params);
+  }
+
+  const searchParams = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null) continue;
+
+    if (Array.isArray(value)) {
+      switch (options?.arrayFormat ?? "repeat") {
+        case "repeat":
+          for (const item of value) {
+            searchParams.append(key, String(item));
+          }
+          break;
+        case "comma":
+          searchParams.set(key, value.join(","));
+          break;
+        case "brackets":
+          for (const item of value) {
+            searchParams.append(`${key}[]`, String(item));
+          }
+          break;
+        case "json":
+          try {
+            searchParams.set(key, JSON.stringify(value));
+          } catch (error) {
+            throw new SerializationError("query", key, error);
+          }
+          break;
+      }
+    } else {
+      searchParams.set(key, String(value));
+    }
+  }
+
+  return searchParams.toString();
+}
+
+export function createCherryClient<TRoutes extends RouteTree | undefined = undefined>(
+  config: ClientConfig<TRoutes>,
+): Client<TRoutes> {
+  const fetcher = config.fetcher ?? defaultFetcher;
+
+  function call<T extends CherryRoute<any, any, any, any>>(
+    route: T,
+    params: InferRouteInput<T>,
+  ): CherryResult<InferRouteOutput<T>> {
+    return ResultAsync.fromPromise(executeRoute(route, params), (error) => {
+      if (error instanceof HttpError) return error;
+      if (error instanceof ValidationError) return error;
+      if (error instanceof NetworkError) return error;
+      if (error instanceof SerializationError) return error;
+      return new UnknownCherryError(error);
+    });
+  }
+
+  async function executeRoute<T extends CherryRoute<any, any, any, any>>(
+    route: T,
+    params: InferRouteInput<T>,
+  ): Promise<InferRouteOutput<T>> {
+    let pathParams: Record<string, unknown> = {};
+    if (route.pathParams) {
+      const result = v.safeParse(route.pathParams, params);
+      if (!result.success) throw new ValidationError("request", result.issues);
+      pathParams = result.output;
+    }
+
+    let queryParams: Record<string, unknown> = {};
+    if (route.queryParams) {
+      const result = v.safeParse(route.queryParams, params);
+      if (!result.success) throw new ValidationError("request", result.issues);
+      queryParams = result.output;
+    }
+
+    let bodyParams: Record<string, unknown> | undefined;
+    if (route.bodyParams) {
+      const result = v.safeParse(route.bodyParams, params);
+      if (!result.success) throw new ValidationError("request", result.issues);
+      bodyParams = result.output;
+    }
+
+    let url = route.path.template;
+    for (const [key, value] of Object.entries(pathParams)) {
+      url = url.replace(`:${key}`, encodeURIComponent(String(value)));
+    }
+
+    const fullUrl = new URL(url, config.baseUrl);
+
+    if (Object.keys(queryParams).length > 0) {
+      fullUrl.search = serializeQueryParams(queryParams, route.queryParamOptions);
+    }
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...(await config.headers?.()),
+    };
+
+    const init: RequestInit = {
+      method: route.method,
+      headers,
+    };
+
+    if (bodyParams && route.method !== "GET") {
+      init.body = JSON.stringify(bodyParams);
+    }
+
+    const req: FetchRequest = {
+      url: fullUrl.toString(),
+      init,
+    };
+
+    let response: Response;
+    try {
+      response = await fetcher(req);
+    } catch (error) {
+      throw new NetworkError(error);
+    }
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => undefined);
+      throw new HttpError(response.status, response.statusText, body);
+    }
+
+    const json = await response.json();
+    const result = v.safeParse(route.response, json);
+    if (!result.success) throw new ValidationError("response", result.issues);
+
+    return result.output;
+  }
+
+  function forgeRouteMethods<T extends RouteTree>(routes: T): RoutesToClient<T> {
+    const out: any = {};
+
+    for (const [key, value] of Object.entries(routes)) {
+      if (value && typeof value === "object" && "method" in value && "path" in value) {
+        out[key] = (params: any) => call(value as any, params);
+      } else if (value && typeof value === "object") {
+        out[key] = forgeRouteMethods(value as RouteTree);
+      }
+    }
+
+    return out;
+  }
+
+  const routes = config.routes ? forgeRouteMethods(config.routes) : {};
+  return { call, ...routes } as Client<TRoutes>;
+}

package/src/errors.ts

@@ -0,0 +1,86 @@
+import { errAsync, ResultAsync } from "neverthrow";
+
+/** Base error class for all Cherry errors */
+export abstract class CherryError extends Error {
+  abstract readonly type: string;
+  abstract readonly retryable: boolean;
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = this.constructor.name;
+  }
+}
+
+/** HTTP response errors (4xx, 5xx) */
+export class HttpError extends CherryError {
+  readonly type = "HttpError";
+  readonly retryable: boolean;
+
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly body?: unknown,
+    cause?: unknown,
+  ) {
+    super(`HTTP ${status}: ${statusText}`, { cause });
+    this.retryable = status >= 500 || status === 429;
+  }
+}
+
+/** Valibot validation errors */
+export class ValidationError extends CherryError {
+  readonly type = "ValidationError";
+  readonly retryable = false;
+
+  constructor(
+    public readonly target: "request" | "response",
+    public readonly issues: unknown[],
+    cause?: unknown,
+  ) {
+    super(`Validation failed for ${target}`, { cause });
+  }
+}
+
+/** Network/fetch errors */
+export class NetworkError extends CherryError {
+  readonly type = "NetworkError";
+  readonly retryable = true;
+
+  constructor(cause?: unknown) {
+    super(`Network error`, { cause });
+  }
+}
+
+/** Serialization errors (e.g., circular references, BigInt in JSON) */
+export class SerializationError extends CherryError {
+  readonly type = "SerializationError";
+  readonly retryable = false;
+
+  constructor(
+    public readonly target: "query" | "body",
+    public readonly key: string,
+    cause?: unknown,
+  ) {
+    super(`Failed to serialize ${target} parameter "${key}"`, { cause });
+  }
+}
+
+/** Catch-all for unexpected errors */
+export class UnknownCherryError extends CherryError {
+  readonly type = "UnknownCherryError";
+  readonly retryable = false;
+
+  constructor(cause?: unknown) {
+    super(`Unknown error`, { cause });
+  }
+}
+
+/** Type guard for CherryError */
+export function isCherryError(error: unknown): error is CherryError {
+  return error instanceof CherryError;
+}
+
+/** Helper to create error ResultAsync */
+export function cherryErr<T>(error: CherryError): ResultAsync<T, CherryError> {
+  return errAsync(error);
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+export { createCherryClient, serializeQueryParams } from "./cherry_client";
+
+export { route } from "./route";
+
+export { path, param, optional, type PathParam, type OptionalParam, type AnyPathParam } from "./path";
+
+export {
+  CherryError,
+  HttpError,
+  ValidationError,
+  NetworkError,
+  SerializationError,
+  UnknownCherryError,
+  isCherryError,
+  cherryErr,
+} from "./errors";
+
+export type {
+  HttpMethod,
+  PathTemplate,
+  CherryRoute,
+  QueryParamOptions,
+  InferRouteInput,
+  InferRouteOutput,
+  CherryResult,
+  FetchRequest,
+  Fetcher,
+  RouteTree,
+  ClientConfig,
+  Client,
+  RoutesToClient,
+} from "./types";

package/src/path.ts

@@ -0,0 +1,70 @@
+// path.ts - Tagged template functions for type-safe path building
+import type { PathTemplate } from "./types";
+
+/** Branded type for path parameter markers */
+declare const PathParamBrand: unique symbol;
+export type PathParam<T extends string = string> = string & {
+  readonly [PathParamBrand]: T;
+};
+
+/** Branded type for optional path parameter markers */
+declare const OptionalParamBrand: unique symbol;
+export type OptionalParam<T extends string = string> = string & {
+  readonly [OptionalParamBrand]: T;
+};
+
+/** Union type for any path param marker */
+export type AnyPathParam = PathParam<string> | OptionalParam<string>;
+
+/** Create a path parameter marker */
+export function param<T extends string>(name: T): PathParam<T> {
+  return `:${name}` as PathParam<T>;
+}
+
+/** Create an optional path parameter marker */
+export function optional<T extends string>(name: T): OptionalParam<T> {
+  return `(:${name})` as OptionalParam<T>;
+}
+
+/**
+ * Tagged template for building path templates.
+ *
+ * @example
+ * ```ts
+ * // Simple path with one param
+ * const userPath = path`/users/${param("id")}`;
+ * // { template: "/users/:id", paramNames: ["id"] }
+ *
+ * // Multiple params
+ * const postPath = path`/users/${param("userId")}/posts/${param("postId")}`;
+ * // { template: "/users/:userId/posts/:postId", paramNames: ["userId", "postId"] }
+ *
+ * // Optional params
+ * const versionedPath = path`/api${optional("version")}/users`;
+ * // { template: "/api(:version)/users", paramNames: ["version"] }
+ *
+ * // No params
+ * const staticPath = path`/health`;
+ * // { template: "/health", paramNames: [] }
+ * ```
+ */
+export function path(
+  strings: TemplateStringsArray,
+  ...params: AnyPathParam[]
+): PathTemplate {
+  const paramNames: string[] = [];
+  let template = strings[0];
+
+  for (let i = 0; i < params.length; i++) {
+    const p = params[i];
+    template += p + strings[i + 1];
+
+    // Extract param name from `:name` or `(:name)`
+    const match = p.match(/^\(?:(\w+)\)?$/);
+    if (match) {
+      paramNames.push(match[1]);
+    }
+  }
+
+  return { template, paramNames };
+}

package/src/route.ts

@@ -0,0 +1,63 @@
+import * as v from "valibot";
+import type { CherryRoute } from "./types";
+
+const HttpMethodSchema = v.picklist(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+
+export function route<
+  TPathParams extends v.BaseSchema<any, any, any> | undefined = undefined,
+  TQueryParams extends v.BaseSchema<any, any, any> | undefined = undefined,
+  TBodyParams extends v.BaseSchema<any, any, any> | undefined = undefined,
+  TResponse extends v.BaseSchema<any, any, any> = v.BaseSchema<any, any, any>,
+>(
+  config: CherryRoute<TPathParams, TQueryParams, TBodyParams, TResponse>,
+): CherryRoute<TPathParams, TQueryParams, TBodyParams, TResponse> {
+  // validate HTTP method
+  v.parse(HttpMethodSchema, config.method);
+
+  // validate availability and content of pathParams schema, if needed
+  if (config.path.paramNames.length > 0) {
+    if (!config.pathParams) {
+      throw new Error(
+        `Route has path params [${config.path.paramNames.join(", ")}] but no pathParams schema`,
+      );
+    }
+
+    const schemaKeys = getSchemaKeys(config.pathParams);
+
+    for (const paramName of config.path.paramNames) {
+      if (!schemaKeys.includes(paramName)) {
+        throw new Error(
+          `Path param ":${paramName}" not found in pathParams schema. ` +
+            `Available: [${schemaKeys.join(", ")}]`,
+        );
+      }
+    }
+
+    for (const schemaKey of schemaKeys) {
+      if (!config.path.paramNames.includes(schemaKey)) {
+        throw new Error(
+          `pathParams schema key "${schemaKey}" not present in path template. ` +
+            `Template params: [${config.path.paramNames.join(", ")}]`,
+        );
+      }
+    }
+  }
+
+  return config as CherryRoute<
+    TPathParams,
+    TQueryParams,
+    TBodyParams,
+    TResponse
+  >;
+}
+
+function getSchemaKeys(schema: v.BaseSchema<any, any, any>): string[] {
+  if (
+    "entries" in schema &&
+    typeof (schema as any).entries === "object" &&
+    (schema as any).entries !== null
+  ) {
+    return Object.keys((schema as any).entries);
+  }
+  return [];
+}

package/src/types.ts

@@ -0,0 +1,107 @@
+import type { BaseSchema, InferInput, InferOutput } from "valibot";
+import type { ResultAsync } from "neverthrow";
+import type { CherryError } from "./errors";
+
+type AnySchema = BaseSchema<any, any, any>;
+
+/** HTTP methods supported by Cherry */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/** Path template result from path() tagged template */
+export type PathTemplate = {
+  template: string; // "/users/:id/posts/:postId"
+  paramNames: string[]; // ["id", "postId"]
+};
+
+/** Route definition with separated parameter schemas */
+export type CherryRoute<
+  TPathParams extends AnySchema | undefined = undefined,
+  TQueryParams extends AnySchema | undefined = undefined,
+  TBodyParams extends AnySchema | undefined = undefined,
+  TResponse extends AnySchema = AnySchema,
+> = {
+  method: HttpMethod;
+  path: PathTemplate;
+  pathParams?: TPathParams;
+  queryParams?: TQueryParams;
+  bodyParams?: TBodyParams;
+  response: TResponse;
+  queryParamOptions?: QueryParamOptions;
+  description?: string;
+};
+
+/** Options for query parameter serialization */
+export type QueryParamOptions = {
+  arrayFormat?: "repeat" | "comma" | "brackets" | "json";
+  customSerializer?: (params: Record<string, unknown>) => string;
+};
+
+type AnyCherryRoute = CherryRoute<any, any, any, any>;
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+
+type InferSchemaInput<T> = T extends AnySchema ? InferInput<T> : {};
+
+type BuildRouteInputFromProps<
+  TPathParams,
+  TQueryParams,
+  TBodyParams
+> = InferSchemaInput<TPathParams> &
+    InferSchemaInput<TQueryParams> &
+    InferSchemaInput<TBodyParams>;
+
+export type InferRouteInput<T> = 
+  T extends { pathParams?: infer TPath; queryParams?: infer TQuery; bodyParams?: infer TBody }
+    ? IsEmptyObject<BuildRouteInputFromProps<TPath, TQuery, TBody>> extends true
+      ? void
+      : Prettify<BuildRouteInputFromProps<TPath, TQuery, TBody>>
+    : never;
+
+/** Infer response output from a route */
+export type InferRouteOutput<T extends AnyCherryRoute> =
+  T["response"] extends AnySchema ? InferOutput<T["response"]> : never;
+
+/** Cherry result type - always ResultAsync */
+export type CherryResult<T> = ResultAsync<T, CherryError>;
+
+/** Fetcher request shape (extensible for middleware) */
+export type FetchRequest = {
+  url: string;
+  init: RequestInit;
+};
+
+/** Fetcher function signature */
+export type Fetcher = (req: FetchRequest) => Promise<Response>;
+
+/** Route tree (supports namespacing via nested objects) */
+export type RouteTree = {
+  [key: string]: AnyCherryRoute | RouteTree;
+};
+
+/** Client configuration */
+export type ClientConfig<TRoutes extends RouteTree | undefined = undefined> = {
+  baseUrl: string;
+  headers?: () => Record<string, string> | Promise<Record<string, string>>;
+  fetcher?: Fetcher;
+  routes?: TRoutes;
+};
+
+export type Client<TRoutes extends RouteTree | undefined = undefined> = {
+  call: <T extends AnyCherryRoute>(
+    route: T,
+    ...args: InferRouteInput<T> extends void ? [] : [params: InferRouteInput<T>]
+  ) => CherryResult<InferRouteOutput<T>>;
+} & (TRoutes extends RouteTree ? RoutesToClient<TRoutes> : {});
+
+/** Convert a nested route tree into a nested client method tree */
+export type RoutesToClient<TRoutes extends RouteTree> = {
+  [K in keyof TRoutes]: TRoutes[K] extends AnyCherryRoute
+    ? InferRouteInput<TRoutes[K]> extends void
+      ? () => CherryResult<InferRouteOutput<TRoutes[K]>>
+      : (params: InferRouteInput<TRoutes[K]>) => CherryResult<InferRouteOutput<TRoutes[K]>>
+    : TRoutes[K] extends RouteTree
+      ? RoutesToClient<TRoutes[K]>
+      : never;
+};