@stiviar/modeled-react 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# @stiviar/react
+
+React bindings for [stiviar](https://github.com/szlkeve/stiviar) — a declarative, type-safe API layer.
+
+## Install
+
+```bash
+npm i @stiviar/react
+```
+
+## Usage
+
+Define your models once:
+
+```ts
+// api.ts
+import { register } from "@stiviar/core";
+import { Todos, TodosSchema, Users, UsersSchema } from "./types";
+
+export const api = register<{
+  users: { type: Users };
+  todos: { type: Todos };
+}>({
+  users: {
+    url: "https://api.example.com/users",
+    schema: UsersSchema,
+  },
+  todos: {
+    url: "https://api.example.com/todos",
+    schema: TodosSchema,
+  },
+});
+
+export const useData = api.useData;
+export const isContractValid = api.isContractValid;
+```
+
+Use it in a component:
+
+```tsx
+// Component.tsx
+import { useData } from "./api";
+
+export function Component() {
+  const { data, isLoading, error } = useData("users");
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>Something went wrong.</p>;
+
+  return <div>user count: {data?.length}</div>;
+}
+```
+
+Types declared for a model flow through the whole codebase — hover `data` in your IDE and see the inferred type, with a compile-time error if your schema and type ever drift apart.
+
+## Testing
+
+Swap the fetch implementation at registration time so components stay testable without a network:
+
+```ts
+export const api = register<TypeModel>(apiModel, {
+  fetchFn: IS_DEV ? mockFetch : fetch,
+});
+```
+
+## API
+
+- `useData(key, params?)` — TanStack Query-backed fetch hook for a registered endpoint
+- `isContractValid(openApiSchema)` — validates a live OpenAPI contract against your registered types
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+import { QueryClient } from '@tanstack/react-query';
+import z from 'zod';
+
+type BaseApiTypeMap = {
+    [stateName: string]: {
+        type: object | string | number | boolean;
+    } & ({
+        params: {
+            [param: string]: string | number;
+        };
+    } | {
+        params?: undefined;
+    });
+};
+type ApiModel<ApiTypeMap extends BaseApiTypeMap> = {
+    [NAME in keyof ApiTypeMap]: {
+        schema: z.ZodType<ApiTypeMap[NAME]["type"]>;
+        url: ApiTypeMap[NAME]["params"] extends object ? (params: ApiTypeMap[NAME]["params"]) => string : string;
+    };
+};
+type UseDataArgs<ApiTypeMap extends BaseApiTypeMap, NAME extends keyof ApiTypeMap> = ApiTypeMap[NAME]["params"] extends object ? [stateName: NAME, params: ApiTypeMap[NAME]["params"]] : [stateName: NAME, params?: undefined];
+type Options = {
+    fetchFn?: (url: string) => Promise<unknown>;
+    baseUrl?: string;
+};
+
+declare function register<ApiTypeMap extends BaseApiTypeMap>(apiModel: ApiModel<ApiTypeMap>, options?: Options): {
+    useData: <NAME extends keyof ApiTypeMap>(...args: UseDataArgs<ApiTypeMap, NAME>) => {
+        data: ApiTypeMap[NAME]["type"] | undefined;
+        isLoading: boolean;
+        error: Error | null;
+    };
+    client: QueryClient;
+    invalidate: <NAME extends string | number>(...args: UseDataArgs<BaseApiTypeMap, NAME>) => Promise<void>;
+};
+
+export { register };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { QueryClient } from '@tanstack/react-query';
+import z from 'zod';
+
+type BaseApiTypeMap = {
+    [stateName: string]: {
+        type: object | string | number | boolean;
+    } & ({
+        params: {
+            [param: string]: string | number;
+        };
+    } | {
+        params?: undefined;
+    });
+};
+type ApiModel<ApiTypeMap extends BaseApiTypeMap> = {
+    [NAME in keyof ApiTypeMap]: {
+        schema: z.ZodType<ApiTypeMap[NAME]["type"]>;
+        url: ApiTypeMap[NAME]["params"] extends object ? (params: ApiTypeMap[NAME]["params"]) => string : string;
+    };
+};
+type UseDataArgs<ApiTypeMap extends BaseApiTypeMap, NAME extends keyof ApiTypeMap> = ApiTypeMap[NAME]["params"] extends object ? [stateName: NAME, params: ApiTypeMap[NAME]["params"]] : [stateName: NAME, params?: undefined];
+type Options = {
+    fetchFn?: (url: string) => Promise<unknown>;
+    baseUrl?: string;
+};
+
+declare function register<ApiTypeMap extends BaseApiTypeMap>(apiModel: ApiModel<ApiTypeMap>, options?: Options): {
+    useData: <NAME extends keyof ApiTypeMap>(...args: UseDataArgs<ApiTypeMap, NAME>) => {
+        data: ApiTypeMap[NAME]["type"] | undefined;
+        isLoading: boolean;
+        error: Error | null;
+    };
+    client: QueryClient;
+    invalidate: <NAME extends string | number>(...args: UseDataArgs<BaseApiTypeMap, NAME>) => Promise<void>;
+};
+
+export { register };