restix 0.0.1

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Z3XS0N
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# restix
+
+**restix** is a strict, type-safe HTTP client builder designed for **CLI tools and backend applications**.
+It lets you define your API **once** as a contract (routes + mappings) and then make requests without rewriting fetch logic, URL building, or manual payload handling.
+
+The goal is simple:
+
+> **Design your API → map it → call it safely**
+
+No runtime magic, no hidden abstractions, no guessing.
+
+---
+
+## Why restix?
+
+When building CLI tools or backend services, you often need to:
+- Call many HTTP endpoints
+- Inject params, query strings, headers, and body data
+- Keep everything type-safe
+- Avoid rewriting request logic over and over
+
+**restix solves this by:**
+- Enforcing **exact input types** per endpoint
+- Preventing extra or missing fields at compile time
+- Automatically injecting params, query, body, and headers
+- Keeping request logic centralized and reusable
+
+---
+
+## Core Concepts
+
+### 1. API Interface (Contract)
+
+You define your API as a **TypeScript interface**.
+Each key represents a route, and its value represents the **exact data shape** allowed.
+
+```ts
+interface API_INTERFACE {
+  'GET /users/{id}': {
+    id: string
+  }
+
+  'POST /users/create': {
+    name: string
+    email: string
+  }
+}
+````
+
+This interface becomes the **single source of truth**.
+
+---
+
+### 2. API Mapping
+
+Each endpoint must be mapped to explain **where data goes**:
+
+* `params` → URL params
+* `query` → query string
+* `body` → request body
+* `headers` → request headers
+
+```ts
+import { apiMap, type API_MAPS, type GET_API } from 'restix'
+
+const api_maps: API_MAPS<API_INTERFACE> = {
+  'GET /users/{id}': {
+    map: apiMap<GET_API<API_INTERFACE, 'GET /users/{id}'>>({
+      params: ['id']
+    }),
+    res: 'json',
+    status: {
+      safe: 200,
+      404: () => 'User not found'
+    }
+  },
+
+  'POST /users/create': {
+    map: apiMap<GET_API<API_INTERFACE, 'POST /users/create'>>({
+      body: ['*']
+    }),
+    res: 'json',
+    status: {
+      safe: 201
+    }
+  }
+}
+```
+
+* `'*'` means **all fields**
+* Explicit keys mean **only those fields**
+
+---
+
+### 3. Creating the Client
+
+```ts
+import { NexAPI } from 'restix'
+
+const api = new NexAPI<API_INTERFACE>(
+  'https://api.example.com',
+  api_maps
+)
+```
+
+You can also provide **default injected data** (headers, query, body, params):
+
+```ts
+const api = new NexAPI<API_INTERFACE>(
+  'https://api.example.com',
+  api_maps,
+  {
+    headers: {
+      authorization: 'Bearer TOKEN'
+    }
+  }
+)
+```
+
+---
+
+### 4. Making Requests (Type-Safe)
+
+```ts
+await api.request('GET /users/{id}', {
+  id: '123'
+})
+```
+
+```ts
+await api.request('POST /users/create', {
+  name: 'John',
+  email: 'john@example.com'
+})
+```
+
+❌ This will **fail at compile time**:
+
+```ts
+api.request('POST /users/create', {
+  name: 'John',
+  email: 'john@example.com',
+  extra: 'not allowed'
+})
+```
+
+Because **restix enforces exact types**.
+
+---
+
+## Key Features
+
+* ✅ Exact object validation (no extra keys)
+* ✅ Route-based type inference
+* ✅ Automatic URL param injection
+* ✅ Automatic query string building
+* ✅ Automatic body & header extraction
+* ✅ CLI-friendly (works perfectly with Bun / Node)
+* ✅ No runtime dependencies
+* ✅ No decorators, no reflection
+
+---
+
+## Designed For
+
+* CLI tools
+* Backend services
+* Internal tooling
+* Automation scripts
+* API SDKs
+* Monorepo shared clients
+
+**Not** designed for browser-heavy frontend frameworks.
+
+---
+
+## Philosophy
+
+restix follows a **contract-first** approach:
+
+* Types are the contract
+* Mapping defines behavior
+* Requests are deterministic
+* Errors are caught at compile time, not runtime
+
+If TypeScript allows it, restix allows it.
+If TypeScript rejects it, restix rejects it too.
+
+---
+
+## Status
+
+This package is **actively evolving**.
+The API is intentionally minimal and strict.
+
+Contributions, ideas, and feedback are welcome.
+
+---
+
+## License
+
+MIT

package/api.d.ts

@@ -0,0 +1,13 @@
+import type { API_MAPS, Exact } from './types';
+export declare class NexAPI<API_INTERFACE extends {
+    [k: string]: any;
+}> {
+    #private;
+    constructor(base: string, api_maps: API_MAPS<API_INTERFACE>, defaults?: {
+        body?: Record<string, string>;
+        params?: Record<string, string>;
+        query?: Record<string, string>;
+        headers?: Record<string, string>;
+    });
+    request<URL extends (keyof API_INTERFACE) & string>(prefix: URL, data: Exact<API_INTERFACE[URL], API_INTERFACE[URL]>): Promise<any>;
+}

package/api.js

@@ -0,0 +1,67 @@
+export class NexAPI {
+    #base = 'http://localhost:5000';
+    #api_maps;
+    #defaults;
+    constructor(base, api_maps, defaults) {
+        this.#base = base;
+        this.#api_maps = api_maps;
+        this.#defaults = defaults ?? {};
+    }
+    async request(prefix, data) {
+        const api = this.#api_maps[prefix];
+        if (!api)
+            return;
+        data = {
+            ...data,
+            ...this.#defaults.body ?? {},
+            ...this.#defaults.headers ?? {},
+            ...this.#defaults.params ?? {},
+            ...this.#defaults.query ?? {}
+        };
+        api.map = {
+            body: [...api.map.body, ...Object.keys(this.#defaults.body ?? {})],
+            params: [...api.map.params, ...Object.keys(this.#defaults.params ?? {})],
+            query: [...api.map.query, ...Object.keys(this.#defaults.query ?? {})],
+            headers: [...api.map.headers, ...Object.keys(this.#defaults.headers ?? {})]
+        };
+        const fetchOptoin = {};
+        let [method, url] = prefix.split(' ');
+        fetchOptoin.method = method;
+        url = `${this.#base}${url}`;
+        if (api.map.params.length > 0)
+            url = this.#injectUrlData(url, api.map.params, data);
+        if (api.map.query.length > 0)
+            url = this.#injectQuery(url, api.map.query, data);
+        if (api.map.body.length > 0)
+            fetchOptoin.body = JSON.stringify(this.#injectData(api.map.body, data));
+        if (api.map.headers.length > 0)
+            fetchOptoin.headers = this.#injectData(api.map.headers, data);
+        console.log(url, method, { ...fetchOptoin });
+        const res = await fetch(url, fetchOptoin);
+        if (res.status === api.status.safe)
+            return await res[api.res]();
+        else if (api.status && api.status[res.status])
+            return api.status[res.status]?.();
+        return undefined;
+    }
+    #injectUrlData(url, params, data) {
+        for (const param of params[0] == '*' ? Object.keys(data) : params)
+            url = url.replace(`{${param}}`, data[param]);
+        return url;
+    }
+    #injectQuery(url, queries, data) {
+        for (const [i, query] of queries.entries()) {
+            if (i == 0)
+                url = `${url}?${query}=${data[query]}`;
+            else
+                url = `${url}&${query}=${data[query]}`;
+        }
+        return url;
+    }
+    #injectData(body, data) {
+        const res = {};
+        for (const k of body[0] == '*' ? Object.keys(data) : body)
+            res[k] = data[k];
+        return res;
+    }
+}

package/api.ts

@@ -0,0 +1,74 @@
+import type { API_MAPS, Exact } from './types'
+
+export class NexAPI<API_INTERFACE extends { [k: string]: any }> {
+    #base = 'http://localhost:5000'
+
+    #api_maps: API_MAPS<API_INTERFACE>
+    #defaults: {
+        body?: Record<string, string>
+        params?: Record<string, string>
+        query?: Record<string, string>
+        headers?: Record<string, string>
+    }
+
+    constructor(base: string, api_maps: API_MAPS<API_INTERFACE>, defaults?: {
+        body?: Record<string, string>
+        params?: Record<string, string>
+        query?: Record<string, string>
+        headers?: Record<string, string>
+    }) {
+        this.#base = base
+        this.#api_maps = api_maps
+        this.#defaults = defaults ?? {}
+    }
+
+    async request<URL extends (keyof API_INTERFACE) & string>(prefix: URL, data: Exact<API_INTERFACE[URL], API_INTERFACE[URL]>) {
+        const api = this.#api_maps[prefix]
+        if (!api) return
+        data = {
+            ...data,
+            ...this.#defaults.body ?? {},
+            ...this.#defaults.headers ?? {},
+            ...this.#defaults.params ?? {},
+            ...this.#defaults.query ?? {}
+        }
+        api.map = {
+            body: [...api.map.body, ...Object.keys(this.#defaults.body ?? {})] as typeof api.map.body,
+            params: [...api.map.params, ...Object.keys(this.#defaults.params ?? {})] as typeof api.map.params,
+            query: [...api.map.query, ...Object.keys(this.#defaults.query ?? {})] as typeof api.map.query,
+            headers: [...api.map.headers, ...Object.keys(this.#defaults.headers ?? {})] as typeof api.map.headers
+        }
+        const fetchOptoin: BunFetchRequestInit = {}
+        let [method, url] = prefix.split(' ') as [string, string]
+        fetchOptoin.method = method
+        url = `${this.#base}${url}`
+        if (api.map.params.length > 0) url = this.#injectUrlData(url, api.map.params, data)
+        if (api.map.query.length > 0) url = this.#injectQuery(url, api.map.query, data)
+        if (api.map.body.length > 0) fetchOptoin.body = JSON.stringify(this.#injectData(api.map.body, data))
+        if (api.map.headers.length > 0) fetchOptoin.headers = this.#injectData(api.map.headers, data)
+        console.log(url, method, { ...fetchOptoin })
+        const res = await fetch(url, fetchOptoin)
+        if (res.status === api.status.safe) return await res[api.res]()
+        else if (api.status && api.status[res.status]) return api.status[res.status]?.()
+        return undefined
+    }
+
+    #injectUrlData(url: string, params: string[], data: Record<string, string>) {
+        for (const param of params[0] == '*' ? Object.keys(data) : params) url = url.replace(`{${param}}`, data[param]!)
+        return url
+    }
+
+    #injectQuery(url: string, queries: string[], data: Record<string, string>) {
+        for (const [i, query] of queries.entries()) {
+            if (i == 0) url = `${url}?${query}=${data[query]}`
+            else url = `${url}&${query}=${data[query]}`
+        }
+        return url
+    }
+
+    #injectData(body: string[], data: Record<string, any>) {
+        const res: typeof data = {}
+        for (const k of body[0] == '*' ? Object.keys(data) : body) res[k] = data[k]
+        return res
+    }
+}

package/bun.lock

@@ -0,0 +1,26 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "restix",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.8", "", { "dependencies": { "bun-types": "1.3.8" } }, "sha512-3LvWJ2q5GerAXYxO2mffLTqOzEu5qnhEAlh48Vnu8WQfnmSwbgagjGZV6BoHKJztENYEDn6QmVd949W4uESRJA=="],
+
+    "@types/node": ["@types/node@25.2.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-BkmoP5/FhRYek5izySdkOneRyXYN35I860MFAGupTdebyE66uZaR+bXLHq8k4DirE5DwQi3NuhvRU1jqTVwUrQ=="],
+
+    "bun-types": ["bun-types@1.3.8", "", { "dependencies": { "@types/node": "*" } }, "sha512-fL99nxdOWvV4LqjmC+8Q9kW3M4QTtTR1eePs94v5ctGqU8OeceWrSUaRw3JYb7tU3FkMIAjkueehrHPPPGKi5Q=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from './api';
+export * from './types';
+export * from './utils';

package/index.js

@@ -0,0 +1,3 @@
+export * from './api';
+export * from './types';
+export * from './utils';

package/index.ts

@@ -0,0 +1,3 @@
+export * from './api';
+export * from './types';
+export * from './utils';

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "restix",
+  "version": "0.0.1",
+  "description": "Type-safe HTTP client builder for CLI tools and backend applications",
+  "main": "index.js",
+  "types": "./index.d.ts",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "license": "MIT"
+}

package/test.test.d.ts

@@ -0,0 +1 @@
+export {};

package/test.test.js

@@ -0,0 +1,13 @@
+import { NexAPI } from './api';
+import { apiMap } from './utils';
+const api_maps = {
+    'GET /users': {
+        map: apiMap(),
+        res: 'json',
+        status: {
+            safe: 200
+        }
+    }
+};
+const api = new NexAPI('http://localhost:5000', api_maps);
+console.log(JSON.stringify(await api.request('GET /users', { selam: 'selam' }), null, 4));

package/test.test.ts

@@ -0,0 +1,19 @@
+import { NexAPI } from './api'
+import type { API_MAPS } from './types'
+import { apiMap } from './utils'
+
+interface API_INTERFACE {
+    'GET /users': {}
+}
+const api_maps: API_MAPS<API_INTERFACE> = {
+    'GET /users': {
+        map: apiMap(),
+        res: 'json',
+        status: {
+            safe: 200
+        }
+    }
+}
+
+const api = new NexAPI<API_INTERFACE>('http://localhost:5000', api_maps)
+console.log(JSON.stringify(await api.request('GET /users', { selam: 'selam' }), null, 4))

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": [
+      "ESNext"
+    ],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": false,
+    "verbatimModuleSyntax": true,
+    "noEmit": false,
+    "declaration": true,
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/types.d.ts

@@ -0,0 +1,19 @@
+export type ApiMapShape<K extends string> = {
+    body: (K | '*')[];
+    params: (K | '*')[];
+    query: (K | '*')[];
+    headers: (K | '*')[];
+};
+export type Exact<T, Shape extends T> = T & Record<Exclude<keyof Shape, keyof T>, never>;
+export interface API_MAP_TYPE<K extends string> {
+    map: ApiMapShape<K>;
+    res: keyof Pick<Response, 'json' | 'text' | 'blob'>;
+    status: {
+        safe: number;
+        [k: number]: () => any;
+    };
+}
+export type API_MAPS<T extends Record<string, any>> = {
+    [K in keyof T]: API_MAP_TYPE<Extract<keyof T[K], string>>;
+};
+export type GET_API<T extends Record<string, any>, K extends keyof T> = keyof T[K];

package/types.ts

@@ -0,0 +1,24 @@
+export type ApiMapShape<K extends string> = {
+    body: (K | '*')[]
+    params: (K | '*')[]
+    query: (K | '*')[]
+    headers: (K | '*')[]
+}
+
+export type Exact<T, Shape extends T> =
+    T & Record<Exclude<keyof Shape, keyof T>, never>
+
+export interface API_MAP_TYPE<K extends string> {
+    map: ApiMapShape<K>
+    res: keyof Pick<Response, 'json' | 'text' | 'blob'>
+    status: {
+        safe: number
+        [k: number]: () => any
+    }
+}
+
+export type API_MAPS<T extends Record<string, any>> = {
+    [K in keyof T]: API_MAP_TYPE<Extract<keyof T[K], string>>
+}
+
+export type GET_API<T extends Record<string, any>, K extends keyof T> = keyof T[K]

package/utils.d.ts

@@ -0,0 +1,2 @@
+import type { ApiMapShape } from './types';
+export declare const apiMap: <K extends string>(options?: Partial<ApiMapShape<K>>) => ApiMapShape<K>;

package/utils.js

@@ -0,0 +1,6 @@
+export const apiMap = (options = {}) => ({
+    body: options.body ?? [],
+    params: options.params ?? [],
+    query: options.query ?? [],
+    headers: options.headers ?? []
+});

package/utils.ts

@@ -0,0 +1,8 @@
+import type { ApiMapShape } from './types';
+
+export const apiMap = <K extends string>(options: Partial<ApiMapShape<K>> = {}): ApiMapShape<K> => ({
+    body: options.body ?? [],
+    params: options.params ?? [],
+    query: options.query ?? [],
+    headers: options.headers ?? []
+})