@neupgroup/mapper 1.0.0 → 1.1.0

package/README.md

@@ -1,27 +1,32 @@
 # Neup.Mapper (Library)
 
-Neup.Mapper is now a small, framework-agnostic TypeScript library focused on two things:
+Neup.Mapper is a small, framework-agnostic TypeScript library that provides:
 
-- Database connectivity via adapter pattern (bring your own driver)
-- HTTP API access via adapter pattern (bring your own client)
+- Database connectivity via an adapter pattern (bring your own driver)
+- HTTP API access via an adapter pattern (bring your own client)
+- A simple config/registry to define multiple named connections ("maps")
 
 ## Install
 
-This project is currently private. Build locally:
+```
+npm install @neupgroup/mapper
+```
+
+If you’re working locally on the source:
 
 ```
 npm install
 npm run build
 ```
 
-Artifacts are emitted to `dist/`.
+Artifacts (`*.js`, `*.d.ts`) are emitted into the project root.
 
-## Usage
+## Quick Start (Adapter Basics)
 
 ### Database
 
 ```
-import { createDb, IDbAdapter } from "neup-mapper";
+import { createDb, IDbAdapter } from "@neupgroup/mapper";
 
 const adapter: IDbAdapter = {
   async connect(config) {
@@ -45,7 +50,7 @@ await db.close();
 ### API
 
 ```
-import { createApiClient, IApiAdapter } from "neup-mapper";
+import { createApiClient, IApiAdapter } from "@neupgroup/mapper";
 
 const http: IApiAdapter = {
   async request(req) {
@@ -58,9 +63,159 @@ const api = createApiClient("https://api.example.com", http, { Authorization: "B
 const res = await api.get("/users");
 ```
 
-## Layout
+## Config & Registry (Multiple Named Maps)
+
+You can define multiple named connections (maps), similar to Firebase/Laravel style configs, and then refer to them in your application.
+
+Create a `mapper.config.ts` in your app:
+
+```
+// mapper.config.ts
+import { defineConfig, IApiAdapter, IDbAdapter } from "@neupgroup/mapper";
+
+// Provide your concrete adapters
+const http: IApiAdapter = {
+  async request(req) {
+    // Make HTTP requests using fetch/axios and return { status, headers, data }
+    return { status: 200, data: { ok: true } };
+  },
+};
+
+const dbAdapter: IDbAdapter = {
+  async connect(config) {
+    // Initialize DB driver with credentials from config
+  },
+  async query(sql, params) {
+    return [];
+  },
+  async close() {},
+};
+
+export default defineConfig({
+  maps: [
+    {
+      kind: "api",
+      name: "core",
+      baseUrl: "https://api.example.com",
+      defaultHeaders: { Authorization: "Bearer <token>" },
+      adapter: http,
+    },
+    {
+      kind: "db",
+      name: "analytics",
+      connection: { host: "db.local", user: "app", password: "secret" },
+      adapter: dbAdapter,
+    },
+  ],
+});
+```
+
+Use the registry in your app code:
+
+```
+import config from "./mapper.config";
+import { loadConfig } from "@neupgroup/mapper";
+
+const maps = loadConfig(config);
+
+// Use API
+const api = maps.api("core");
+const res = await api.get("/users");
+
+// Use DB
+const db = maps.db("analytics");
+await db.connect({ host: "db.local" });
+const rows = await db.query("SELECT * FROM events WHERE kind = ?", ["click"]);
+await db.close();
+
+// Introspection
+maps.list(); // [{ name: "core", kind: "api" }, { name: "analytics", kind: "db" }]
+```
+
+## Global `mapper()` API (No App Init)
+
+If you prefer a PHP‑style fluent syntax without explicit app initialization, use the global `mapper()` function:
+
+### Access existing maps (registered via config)
+
+```
+import appConfig from './mapper.config';
+import { useConfig, mapper } from '@neupgroup/mapper';
+
+// Register once (e.g., at app entry) — then use anywhere
+useConfig(appConfig);
+
+// DB usage
+const usersTable = mapper('analytics').table('users');
+const allUsers = await usersTable.selectAll();
+const activeUsers = await usersTable.query('WHERE status = ?', ['active']);
+
+// API usage
+const usersEndpoint = mapper('core').path('/users');
+const res = await usersEndpoint.get();
+```
+
+### Create ephemeral maps with chaining
+
+```
+import { mapper } from '@neupgroup/mapper';
+import type { IDbAdapter, IApiAdapter } from '@neupgroup/mapper';
+
+const dbAdapter: IDbAdapter = { /* implement connect/query/close */ };
+const httpAdapter: IApiAdapter = { /* implement request */ };
+
+// Create and register a DB map
+mapper()
+  .create('tempDb', 'db')
+  .host('localhost')
+  .dbname('app')
+  .user('user')
+  .pass('secret')
+  .adapter(dbAdapter)
+  .save();
+
+// Use it anywhere
+const t = mapper('tempDb').table('logs');
+const rows = await t.query('WHERE level = ?', ['error']);
+
+// Create and register an API map
+mapper()
+  .create('tempApi', 'api')
+  .baseUrl('https://api.example.com')
+  .header('Authorization', 'Bearer token')
+  .adapter(httpAdapter)
+  .save();
+
+const endpoint = mapper('tempApi').path('/events');
+await endpoint.post({ type: 'click' });
+```
+
+Notes:
+- `mapper('name').table('...')` is for DB maps; `mapper('name').path('...')` is for API maps.
+- Duplicate map names are prevented; attempting to re‑use a name throws a clear error.
+- The builder requires `create(name, kind)` and `adapter(...)` before `save()`.
+
+### Notes
+
+- The registry does not auto-connect databases; call `db.connect()` when appropriate.
+- The API client merges `defaultHeaders` with any per-call headers.
+- Each map is keyed by a unique `name`; use `maps.get(name)` if you don’t know the type at compile time.
+
+## API Reference
+
+- `createDb(adapter: IDbAdapter): Db`
+- `createApiClient(baseUrl: string, adapter: IApiAdapter, defaultHeaders?: Record<string,string>): ApiClient`
+- `defineConfig(config: MapperConfig): MapperConfig`
+- `createRegistry(config: MapperConfig): MapperRegistry`
+- `loadConfig(config: MapperConfig): MapperRegistry` (alias)
+
+## Publish
+
+This package is configured for public publish (scoped):
+
+```
+npm run build
+npm publish --access public
+```
 
-- Source files live at the project root: `index.ts`, `db.ts`, `api.ts`.
-- Build emits to `dist/` with `index.js` and `index.d.ts` for consumers.
-- No React/Next.js UI is included; the project is library-only.
-- Add any DB driver or HTTP client as dependencies in your own app.
+Ensure your `package.json` has `"private": false` and `"publishConfig": { "access": "public" }`.

package/config.d.ts

@@ -0,0 +1,39 @@
+import { type ApiAdapter, type ApiClient } from "./api";
+import { type DbAdapter, type Db } from "./db";
+export type MapKind = "api" | "db";
+export interface ApiMapConfig {
+    kind: "api";
+    name: string;
+    baseUrl?: string;
+    defaultHeaders?: Record<string, string>;
+    adapter: ApiAdapter;
+}
+export interface DbMapConfig {
+    kind: "db";
+    name: string;
+    connection?: Record<string, unknown>;
+    adapter: DbAdapter;
+}
+export type MapConfig = ApiMapConfig | DbMapConfig;
+export interface MapperConfig {
+    maps: MapConfig[];
+}
+export interface MapperRegistry {
+    /** Get a named API client */
+    api: (name: string) => ApiClient;
+    /** Get a named DB client */
+    db: (name: string) => Db;
+    /** Get any named client (API or DB) */
+    get: (name: string) => ApiClient | Db;
+    /** List registered maps */
+    list: () => {
+        name: string;
+        kind: MapKind;
+    }[];
+}
+/** Helper to define config with proper type inference */
+export declare function defineConfig(config: MapperConfig): MapperConfig;
+/** Create a registry of named API/DB maps from configuration */
+export declare function createRegistry(config: MapperConfig): MapperRegistry;
+/** alias */
+export declare const loadConfig: typeof createRegistry;

package/config.js

@@ -0,0 +1,49 @@
+import { createApiClient } from "./api";
+import { createDb } from "./db";
+/** Helper to define config with proper type inference */
+export function defineConfig(config) {
+    return config;
+}
+/** Create a registry of named API/DB maps from configuration */
+export function createRegistry(config) {
+    const entries = new Map();
+    for (const m of config.maps) {
+        if (!m.name)
+            throw new Error("Map config requires a unique 'name'");
+        if (entries.has(m.name))
+            throw new Error(`Duplicate map name '${m.name}'`);
+        if (m.kind === "api") {
+            const client = createApiClient(m.baseUrl ?? "", m.adapter, m.defaultHeaders);
+            entries.set(m.name, { kind: "api", value: client });
+        }
+        else if (m.kind === "db") {
+            const db = createDb(m.adapter);
+            // Optional: pre-connect using provided connection config.
+            // Consumers may choose to call db.connect() themselves.
+            // if (m.connection) await db.connect(m.connection);
+            entries.set(m.name, { kind: "db", value: db });
+        }
+    }
+    const getApi = (name) => {
+        const entry = entries.get(name);
+        if (!entry || entry.kind !== "api")
+            throw new Error(`API map '${name}' not found`);
+        return entry.value;
+    };
+    const getDb = (name) => {
+        const entry = entries.get(name);
+        if (!entry || entry.kind !== "db")
+            throw new Error(`DB map '${name}' not found`);
+        return entry.value;
+    };
+    const get = (name) => {
+        const entry = entries.get(name);
+        if (!entry)
+            throw new Error(`Map '${name}' not found`);
+        return entry.value;
+    };
+    const list = () => Array.from(entries.entries()).map(([name, e]) => ({ name, kind: e.kind }));
+    return { api: getApi, db: getDb, get, list };
+}
+/** alias */
+export const loadConfig = createRegistry;

package/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./db";
 export * from "./api";
+export * from "./config";
+export * from "./mapper";

package/index.js

@@ -1,2 +1,4 @@
 export * from "./db";
 export * from "./api";
+export * from "./config";
+export * from "./mapper";

package/mapper.d.ts

@@ -0,0 +1,59 @@
+import { type ApiAdapter, type ApiClient } from "./api";
+import { type DbAdapter, type Db, type QueryParams } from "./db";
+import type { MapKind, MapperConfig } from "./config";
+export declare function useConfig(config: MapperConfig): void;
+export declare function list(): {
+    name: string;
+    kind: MapKind;
+}[];
+export interface ApiPath {
+    get<T = unknown>(headers?: Record<string, string>): Promise<{
+        status: number;
+        headers?: Record<string, string>;
+        data?: T;
+    }>;
+    post<T = unknown>(body?: unknown, headers?: Record<string, string>): Promise<{
+        status: number;
+        headers?: Record<string, string>;
+        data?: T;
+    }>;
+    put<T = unknown>(body?: unknown, headers?: Record<string, string>): Promise<{
+        status: number;
+        headers?: Record<string, string>;
+        data?: T;
+    }>;
+    delete<T = unknown>(headers?: Record<string, string>): Promise<{
+        status: number;
+        headers?: Record<string, string>;
+        data?: T;
+    }>;
+}
+export interface DbTable {
+    selectAll<T = unknown>(): Promise<T[]>;
+    query<T = unknown>(sqlSuffix?: string, params?: QueryParams): Promise<T[]>;
+}
+export interface MapperHandle {
+    name(): string;
+    kind(): MapKind;
+    client(): ApiClient | Db;
+    table(name: string): DbTable;
+    path(p: string): ApiPath;
+}
+export interface MapperBuilderStart {
+    create(name: string, kind: MapKind): MapperBuilder;
+}
+export interface MapperBuilder {
+    adapter(adapter: ApiAdapter | DbAdapter): MapperBuilder;
+    save(): MapperHandle;
+    baseUrl(url: string): MapperBuilder;
+    headers(headers: Record<string, string>): MapperBuilder;
+    header(key: string, value: string): MapperBuilder;
+    host(host: string): MapperBuilder;
+    dbname(name: string): MapperBuilder;
+    user(user: string): MapperBuilder;
+    pass(pass: string): MapperBuilder;
+    port(port: number): MapperBuilder;
+    option(key: string, value: unknown): MapperBuilder;
+}
+export declare function mapper(): MapperBuilderStart;
+export declare function mapper(name: string): MapperHandle;

package/mapper.js

@@ -0,0 +1,117 @@
+import { createApiClient } from "./api";
+import { createDb } from "./db";
+const registry = new Map();
+function ensureUnique(name) {
+    if (registry.has(name))
+        throw new Error(`Duplicate map name '${name}'`);
+}
+export function useConfig(config) {
+    for (const m of config.maps) {
+        ensureUnique(m.name);
+        if (m.kind === "api") {
+            const client = createApiClient(m.baseUrl ?? "", m.adapter, m.defaultHeaders);
+            registry.set(m.name, { kind: "api", value: client });
+        }
+        else {
+            const db = createDb(m.adapter);
+            registry.set(m.name, { kind: "db", value: db });
+        }
+    }
+}
+export function list() {
+    return Array.from(registry.entries()).map(([name, e]) => ({ name, kind: e.kind }));
+}
+function asHandle(name, entry) {
+    const base = {
+        name: () => name,
+        kind: () => entry.kind,
+        client: () => entry.value,
+    };
+    const table = (t) => {
+        if (entry.kind !== "db")
+            throw new Error(`Map '${name}' is not a DB. Use path() for API.`);
+        const db = entry.value;
+        return {
+            selectAll: () => db.query(`SELECT * FROM ${t}`),
+            query: (suffix, params) => {
+                const sql = suffix ? `SELECT * FROM ${t} ${suffix}` : `SELECT * FROM ${t}`;
+                return db.query(sql, params);
+            },
+        };
+    };
+    const path = (p) => {
+        if (entry.kind !== "api")
+            throw new Error(`Map '${name}' is not an API. Use table() for DB.`);
+        const api = entry.value;
+        const normalized = p.startsWith("/") ? p : `/${p}`;
+        return {
+            get: (headers) => api.get(normalized, headers),
+            post: (body, headers) => api.post(normalized, body, headers),
+            put: (body, headers) => api.put(normalized, body, headers),
+            delete: (headers) => api.delete(normalized, headers),
+        };
+    };
+    return { ...base, table, path };
+}
+class Builder {
+    constructor() {
+        this.conf = {};
+    }
+    create(name, kind) {
+        this.conf.name = name;
+        this.conf.kind = kind;
+        return this;
+    }
+    adapter(adapter) {
+        this.conf.adapter = adapter;
+        return this;
+    }
+    // API
+    baseUrl(url) { var _a; (_a = this.conf).api ?? (_a.api = {}); this.conf.api.baseUrl = url; return this; }
+    headers(headers) {
+        var _a;
+        (_a = this.conf).api ?? (_a.api = {});
+        const current = this.conf.api.defaultHeaders ?? {};
+        this.conf.api.defaultHeaders = { ...current, ...headers };
+        return this;
+    }
+    header(key, value) { return this.headers({ [key]: value }); }
+    // DB
+    ensureConn() {
+        var _a;
+        (_a = this.conf).db ?? (_a.db = {});
+        if (!this.conf.db.connection)
+            this.conf.db.connection = {};
+    }
+    host(host) { this.ensureConn(); this.conf.db.connection.host = host; return this; }
+    dbname(name) { this.ensureConn(); this.conf.db.connection.dbname = name; return this; }
+    user(user) { this.ensureConn(); this.conf.db.connection.user = user; return this; }
+    pass(pass) { this.ensureConn(); this.conf.db.connection.pass = pass; return this; }
+    port(port) { this.ensureConn(); this.conf.db.connection.port = port; return this; }
+    option(key, value) { this.ensureConn(); this.conf.db.connection[key] = value; return this; }
+    save() {
+        const name = this.conf.name;
+        const kind = this.conf.kind;
+        const adapter = this.conf.adapter;
+        if (!name || !kind || !adapter)
+            throw new Error("Builder requires name, kind, and adapter before save()");
+        ensureUnique(name);
+        if (kind === "api") {
+            const client = createApiClient(this.conf.api?.baseUrl ?? "", adapter, this.conf.api?.defaultHeaders);
+            registry.set(name, { kind: "api", value: client });
+            return asHandle(name, registry.get(name));
+        }
+        const db = createDb(adapter);
+        registry.set(name, { kind: "db", value: db });
+        return asHandle(name, registry.get(name));
+    }
+}
+export function mapper(name) {
+    if (typeof name === "string") {
+        const entry = registry.get(name);
+        if (!entry)
+            throw new Error(`Map '${name}' not found. Register with useConfig() or builder.`);
+        return asHandle(name, entry);
+    }
+    return new Builder();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neupgroup/mapper",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "private": false,
   "type": "module",
   "main": "index.js",