void-snippets-monorepo 0.1.1

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "void-snippets-monorepo",
+  "private": false,
+  "version": "0.1.1",
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "tsup": "^8.0.0"
+  },
+  "scripts": {
+    "build": "pnpm -r run build",
+    "build:core": "pnpm --filter @void-snippets/core run build",
+    "build:client": "pnpm --filter @void-snippets/client run build",
+    "build:react": "pnpm --filter @void-snippets/react run build",
+    "dev": "pnpm -r run dev",
+    "publish:all": "pnpm -r publish --access public --no-git-checks",
+    "version:bump": "pnpm -r exec npm version"
+  }
+}

package/packages/client/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@void-snippets/client",
+  "version": "0.3.0",
+  "description": "Framework-agnostic HTTP resource service for TypeScript projects",
+  "homepage": "https://void-snippets.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shahtirthhh/void-snippets.git",
+    "directory": "packages/client"
+  },
+  "bugs": {
+    "url": "https://github.com/shahtirthhh/void-snippets/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "keywords": [
+    "axios",
+    "typescript",
+    "api",
+    "void-snippets",
+    "resource"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@void-snippets/core": "workspace:*",
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/packages/client/src/configure.ts

@@ -0,0 +1,34 @@
+import type { AxiosInstance } from "axios";
+
+let _instance: AxiosInstance | null = null;
+
+/**
+ * Registers your axios instance globally.
+ * Call this once at your app's entry point before using any service.
+ *
+ * @example
+ * import axios from 'axios';
+ * import { configure } from '@void-snippets/client';
+ *
+ * const axiosInstance = axios.create({ baseURL: 'https://api.example.com' });
+ * configure(axiosInstance);
+ */
+export function configure(instance: AxiosInstance): void {
+  _instance = instance;
+}
+
+/**
+ * @internal — used by BaseApiService, not part of the public API.
+ */
+export function getConfiguredInstance(): AxiosInstance {
+  if (!_instance) {
+    throw new Error(
+      "[@void-snippets/client] No axios instance configured.\n" +
+        "Call configure(axiosInstance) once at your app entry point before using any resource service.\n\n" +
+        "Example:\n" +
+        "  import { configure } from '@void-snippets/client';\n" +
+        "  configure(myAxiosInstance);"
+    );
+  }
+  return _instance;
+}

package/packages/client/src/index.ts

@@ -0,0 +1,4 @@
+export { configure } from "./configure";
+export { BaseApiService } from "./services/base-api.service";
+export { ResourceService } from "./services/resource-api.service";
+export { handleApiError } from "./utils/handle-api-error";

package/packages/client/src/services/base-api.service.ts

@@ -0,0 +1,26 @@
+import type { AxiosInstance } from "axios";
+import { getConfiguredInstance } from "../configure";
+
+/**
+ * Abstract base for all resource services.
+ * Automatically uses the axios instance registered via configure().
+ */
+export abstract class BaseApiService {
+  protected readonly endpoint: string;
+
+  constructor(endpoint: string) {
+    this.endpoint = endpoint;
+  }
+
+  /**
+   * Returns the globally configured axios instance.
+   * Lazy-evaluated so configure() can be called after class instantiation.
+   */
+  protected get http(): AxiosInstance {
+    return getConfiguredInstance();
+  }
+
+  protected getFullUrl(path: string): string {
+    return `${this.endpoint}${path}`;
+  }
+}

package/packages/client/src/services/resource-api.service.ts

@@ -0,0 +1,117 @@
+import type {
+  VSQueryParams,
+  VSDefaultPaginatedResponse,
+  VSDefaultSingleResponse,
+} from "@void-snippets/core";
+import { handleApiError } from "../utils/handle-api-error";
+import { BaseApiService } from "./base-api.service";
+
+/**
+ * Generic CRUD resource service. Extend this class for each API resource.
+ *
+ * @typeParam TId        - The type of the resource's identifier (e.g., string)
+ * @typeParam TBase      - The base entity type returned in list responses
+ * @typeParam TDetail    - The detailed entity type returned in single-item responses (defaults to TBase)
+ * @typeParam TCreate    - The payload type for create operations (defaults to Partial<TBase>)
+ * @typeParam TUpdate    - The payload type for update operations (defaults to Partial<TBase>)
+ * @typeParam TListRaw   - Raw API list response shape (defaults to VSDefaultPaginatedResponse<TBase>)
+ * @typeParam TSingleRaw - Raw API single-item response shape (defaults to VSDefaultSingleResponse<TDetail>)
+ *
+ * @example
+ * import { ResourceService } from '@void-snippets/client';
+ * import type { Contact } from './contacts.types';
+ *
+ * export class ContactsApiService extends ResourceService<
+ *   Contact.Id,
+ *   Contact.Base,
+ *   Contact.WithCreatedBy,
+ *   Contact.Apis.CreatePayload,
+ *   Contact.Apis.UpdatePayload
+ * > {
+ *   constructor() {
+ *     super('/contacts');
+ *   }
+ * }
+ *
+ * export const ContactsApis = new ContactsApiService();
+ */
+export class ResourceService<
+  TId,
+  TBase,
+  TDetail = TBase,
+  TCreate = Partial<TBase>,
+  TUpdate = Partial<TBase>,
+  TListRaw = VSDefaultPaginatedResponse<TBase>,
+  TSingleRaw = VSDefaultSingleResponse<TDetail>,
+> extends BaseApiService {
+  declare readonly __types: {
+    id: TId;
+    base: TBase;
+    detail: TDetail;
+    create: TCreate;
+    update: TUpdate;
+    listRaw: TListRaw;
+    singleRaw: TSingleRaw;
+  };
+
+  constructor(endpoint: string) {
+    super(endpoint);
+  }
+
+  async list(params?: VSQueryParams): Promise<TListRaw> {
+    try {
+      const { data } = await this.http.get<TListRaw>(this.getFullUrl(""), {
+        params,
+      });
+      return data;
+    } catch (error) {
+      handleApiError(error);
+    }
+  }
+
+  async get(id: TId): Promise<TSingleRaw> {
+    try {
+      const { data } = await this.http.get<TSingleRaw>(
+        `${this.getFullUrl("")}/${String(id)}`
+      );
+      return data;
+    } catch (error) {
+      handleApiError(error);
+    }
+  }
+
+  async create(payload: TCreate): Promise<TSingleRaw> {
+    try {
+      const { data } = await this.http.post<TSingleRaw>(
+        this.getFullUrl(""),
+        payload
+      );
+      return data;
+    } catch (error) {
+      handleApiError(error);
+    }
+  }
+
+  async update(id: TId, payload: TUpdate): Promise<TSingleRaw> {
+    try {
+      const { data } = await this.http.patch<TSingleRaw>(
+        `${this.getFullUrl("")}/${String(id)}`,
+        payload
+      );
+      return data;
+    } catch (error) {
+      handleApiError(error);
+    }
+  }
+
+  async delete(id: TId): Promise<TSingleRaw> {
+    try {
+      const { data } = await this.http.delete<TSingleRaw>(
+        `${this.getFullUrl("")}/${String(id)}`
+      );
+      return data;
+    } catch (error) {
+      handleApiError(error);
+    }
+  }
+}

package/packages/client/src/utils/handle-api-error.ts

@@ -0,0 +1,20 @@
+import { AxiosError } from "axios";
+
+/**
+ * Normalizes axios and generic errors into a standard Error.
+ * Always throws — return type is `never`.
+ */
+export function handleApiError(error: unknown): never {
+  if (error instanceof AxiosError) {
+    const serverMessage =
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (error.response?.data as { message?: string })?.message;
+    throw new Error(serverMessage ?? error.message);
+  }
+
+  if (error instanceof Error) {
+    throw error;
+  }
+
+  throw new Error("An unexpected error occurred.");
+}

package/packages/client/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/packages/client/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  external: ["@void-snippets/core"],
+});

package/packages/core/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@void-snippets/core",
+  "version": "0.3.0",
+  "description": "Core types and utilities for void-snippets packages",
+  "homepage": "https://void-snippets.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shahtirthhh/void-snippets.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/shahtirthhh/void-snippets/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "keywords": [
+    "typescript",
+    "void-snippets",
+    "types"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/packages/core/src/id.ts

@@ -0,0 +1,19 @@
+/**
+ * Creates a branded (nominal) type from a primitive.
+ *
+ * Branded types prevent accidental mixing of structurally identical
+ * but semantically different IDs at compile time.
+ *
+ * @typeParam K - The underlying primitive type (usually `string`)
+ * @typeParam T - A unique brand tag per entity (use a string literal)
+ *
+ * @example
+ * type ContactId = VSId<string, 'Contact'>;
+ * type UserId    = VSId<string, 'User'>;
+ *
+ * declare const contactId: ContactId;
+ * declare let   userId: UserId;
+ *
+ * userId = contactId; // ✅ TypeScript error — brands don't match
+ */
+export type VSId<K, T> = K & { __brand: T };

package/packages/core/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./types/index";
+export type { VSId } from "./id";
+export { stringToId } from "./string-to-id";
+export { catchError } from "./utils/catch-error";

package/packages/core/src/string-to-id.ts

@@ -0,0 +1,22 @@
+import type { VSId } from "./id";
+
+/**
+ * Casts a plain `string` to a branded `VSId` type.
+ *
+ * Use at runtime boundaries (e.g. URL params, API responses, localStorage)
+ * where you receive a raw string and need the correct branded ID type.
+ *
+ * @typeParam T - Must be a `VSId<string, Brand>` type
+ *
+ * @example
+ * import type { VSId } from '@void-snippets/core';
+ * import { stringToId } from '@void-snippets/core';
+ *
+ * type ContactId = VSId<string, 'Contact'>;
+ *
+ * const raw = params.contactId; // string
+ * const id = stringToId<ContactId>(raw); // ContactId ✅
+ */
+export const stringToId = <T extends VSId<string, unknown>>(
+  id: string
+): T => id as unknown as T;

package/packages/core/src/types/index.ts

@@ -0,0 +1,86 @@
+// ============================================================================
+// PAGINATION
+// ============================================================================
+
+export interface VSPagination {
+  page: number;
+  limit: number;
+  totalPages: number;
+  totalDocuments: number;
+}
+
+export interface VSQueryParams {
+  page?: number;
+  limit?: number;
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// DEFAULT API RESPONSE SHAPES
+// These are the shapes the library uses out-of-the-box.
+// If your API returns a different shape, provide custom adapters.
+// ============================================================================
+
+export interface VSDefaultPaginatedData<T> {
+  items: T[];
+  page: number;
+  limit: number;
+  totalPages: number;
+  totalDocuments: number;
+}
+
+export interface VSDefaultPaginatedResponse<T> {
+  data: VSDefaultPaginatedData<T>;
+}
+
+export interface VSDefaultSingleResponse<T> {
+  data: T;
+}
+
+// ============================================================================
+// ADAPTER INTERFACES
+// Adapters decouple the library from any specific API response shape.
+// Pass them to createResourceHooks() if your API shape differs from defaults.
+//
+// @example
+//   const adapters: VSAdapters<MyListRes, User, MySingleRes, UserDetail> = {
+//     fromList: (raw) => ({ items: raw.results, pagination: { ... } }),
+//     fromSingle: (raw) => raw.payload,
+//   };
+// ============================================================================
+
+export interface VSListResult<TBase> {
+  items: TBase[];
+  pagination: VSPagination;
+}
+
+export interface VSAdapters<TListRaw, TBase, TSingleRaw, TDetail> {
+  fromList: (raw: TListRaw) => VSListResult<TBase>;
+  fromSingle: (raw: TSingleRaw) => TDetail;
+}
+
+// ============================================================================
+// DEFAULT ADAPTERS FACTORY
+// Works out-of-the-box if your API matches VSDefaultPaginatedResponse /
+// VSDefaultSingleResponse. Zero config needed in that case.
+// ============================================================================
+
+export function createDefaultAdapters<TBase, TDetail>(): VSAdapters<
+  VSDefaultPaginatedResponse<TBase>,
+  TBase,
+  VSDefaultSingleResponse<TDetail>,
+  TDetail
+> {
+  return {
+    fromList: (raw) => ({
+      items: raw.data.items,
+      pagination: {
+        page: raw.data.page,
+        limit: raw.data.limit,
+        totalPages: raw.data.totalPages,
+        totalDocuments: raw.data.totalDocuments,
+      },
+    }),
+    fromSingle: (raw) => raw.data,
+  };
+}

package/packages/core/src/utils/catch-error.ts

@@ -0,0 +1,20 @@
+/**
+ * Wraps a Promise and returns a [error, null] | [null, data] tuple.
+ * Eliminates try/catch at the call site — Go-style error handling for TypeScript.
+ *
+ * @example
+ * const [err, data] = await catchError(fetchUser(id));
+ * if (err) { // handle error }
+ * // data is correctly typed as T here
+ */
+export async function catchError<T>(
+  promise: Promise<T>
+): Promise<[Error, null] | [null, T]> {
+  try {
+    const data = await promise;
+    return [null, data];
+  } catch (error) {
+    if (error instanceof Error) return [error, null];
+    return [new Error(String(error)), null];
+  }
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/packages/core/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+});

package/packages/react/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@void-snippets/react",
+  "version": "0.6.0",
+  "description": "TanStack Query resource hooks factory, Socket.IO hooks factory, type-safe routing contract, and general-purpose React hooks",
+  "homepage": "https://void-snippets.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shahtirthhh/void-snippets.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/shahtirthhh/void-snippets/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "keywords": [
+    "react",
+    "tanstack-query",
+    "react-query",
+    "hooks",
+    "api",
+    "socket.io",
+    "websocket",
+    "routing",
+    "react-router",
+    "type-safe",
+    "void-snippets",
+    "createResourceHooks",
+    "createSocketHooks",
+    "createRouteContract",
+    "useTypedSearchParams",
+    "useModal",
+    "usePagination",
+    "useAsyncState",
+    "useAlertMessage",
+    "useCallTimer"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "@void-snippets/client": ">=0.1.0",
+    "socket.io-client": ">=4.6.0",
+    "react-router": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "socket.io-client": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "@void-snippets/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "react": "^18.0.0",
+    "react-router": "^7.0.0",
+    "socket.io-client": "^4.7.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}