@neupgroup/mapper 1.1.0 → 1.2.1

package/README.md

@@ -1,221 +1,37 @@
-# Neup.Mapper (Library)
-
-Neup.Mapper is a small, framework-agnostic TypeScript library that provides:
-
-- 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
-
-```
-npm install @neupgroup/mapper
-```
-
-If you’re working locally on the source:
-
-```
-npm install
-npm run build
-```
-
-Artifacts (`*.js`, `*.d.ts`) are emitted into the project root.
-
-## Quick Start (Adapter Basics)
-
-### Database
-
-```
-import { createDb, IDbAdapter } from "@neupgroup/mapper";
-
-const adapter: IDbAdapter = {
-  async connect(config) {
-    // initialize your driver, e.g., pg, mysql2, sqlite, etc.
-  },
-  async query(sql, params) {
-    // delegate to your driver
-    return [];
-  },
-  async close() {
-    // close driver resources
-  },
-};
-
-const db = createDb(adapter);
-await db.connect({ host: "localhost" });
-const rows = await db.query("SELECT 1");
-await db.close();
-```
-
-### API
-
-```
-import { createApiClient, IApiAdapter } from "@neupgroup/mapper";
-
-const http: IApiAdapter = {
-  async request(req) {
-    // use fetch/axios/undici, return { status, headers, data }
-    return { status: 200, data: { ok: true } };
-  },
-};
-
-const api = createApiClient("https://api.example.com", http, { Authorization: "Bearer token" });
-const res = await api.get("/users");
-```
-
-## 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
-```
-
-Ensure your `package.json` has `"private": false` and `"publishConfig": { "access": "public" }`.
+# @neupgroup/mapper
+
+Core library for Neup.Mapper. Provides simple schema registration utilities that can be expanded over time.
+
+## Install
+
+```bash
+npm install @neupgroup/mapper
+```
+
+## Usage
+
+```ts
+import Mapper from '@neupgroup/mapper';
+
+const mapper = new Mapper();
+
+mapper.register({
+  name: 'User',
+  fields: [
+    { name: 'id', type: 'string' },
+    { name: 'email', type: 'string' },
+    { name: 'createdAt', type: 'date' },
+  ],
+});
+
+console.log(mapper.list());
+```
+
+## Build
+
+```bash
+npx tsc -p ./tsconfig.json
+```
+
+Outputs are generated to `dist/` with type declarations.
+

package/dist/docs.d.ts

@@ -0,0 +1,3 @@
+export declare const documentationMd = "\n# Mapper Library Documentation\n\nWelcome to `@neupgroup/mapper`. This guide covers:\n- Installation\n- Configuring connections (DSL and UI)\n- Using connections in code\n- Creating schemas (ORM)\n- Configuring and using schemas\n- CRUD operations: insert, update, delete, fetch\n- Error handling and troubleshooting\n\n---\n\n## Installation\n\n- Install from npm:\n  `npm install @neupgroup/mapper`\n- In this workspace, the app depends on the library via `workspace:*`. Build the library when you update it:\n  `cd library && npm run build`\n- Import helpers:\n  `import { parseConnectionsDsl, toNormalizedConnections } from '@neupgroup/mapper'`\n\n---\n\n## Configure Connections\n\nYou can configure connections in two ways:\n\n1) DSL File (recommended)\n2) UI Configure page (runtime setup)\n\n### 1) DSL Format\n\nCreate `connections.dsl` at your project root:\n\n```\nconnections = [\n  mysql_prod: {\n    type: mysql\n    host: 127.0.0.1\n    port: 3306\n    user: root\n    password: \"s3cr3t\"\n    database: appdb\n  }\n\n  mongo_dev: {\n    type: mongodb\n    uri: \"mongodb://127.0.0.1:27017\"\n    database: devdb\n  }\n\n  firestore_local: {\n    type: firestore\n    projectId: my-project\n    applicationDefault: true\n  }\n\n  http_api: {\n    type: api\n    baseUrl: \"https://api.example.com\"\n    token: \"abc123\"\n  }\n]\n```\n\nNotes:\n- `type` (or `dbType`) defaults to `api` if omitted.\n- Values can be unquoted or quoted; comments using `#` are ignored.\n\nParse and normalize:\n\n```ts\nimport { parseConnectionsDsl, toNormalizedConnections } from '@neupgroup/mapper'\n\nconst text = await fs.promises.readFile('connections.dsl', 'utf8')\nconst envMap = parseConnectionsDsl(text)\nconst connections = toNormalizedConnections(envMap)\n// connections: Array<{ name, type, key }>\n```\n\n### 2) UI Configure Page\n\n- Go to `/configure` to define connections at runtime.\n- Use \"Generate collective env\" to produce `connections.dsl` from configured connections.\n- Download the file and commit it or load at startup.\n\n---\n\n## Use Connections in Code\n\n### Normalize and route by type\n\n```ts\nimport { parseConnectionsDsl, toNormalizedConnections } from '@neupgroup/mapper'\nimport { connection, schema } from '@neupgroup/mapper'\n\nconst text = await fs.promises.readFile('connections.dsl', 'utf8')\nconst envMap = parseConnectionsDsl(text)\nconst conns = toNormalizedConnections(envMap)\n\n// Register connections\nconst conRegistry = connection()\nfor (const c of conns) {\n  conRegistry.register({ name: c.name, type: c.type, key: c.key })\n}\n\n// Use with schemas\nconst sm = schema(conRegistry)\n```\n\n### Direct construction\n\n```ts\nconst conRegistry = connection()\nconRegistry.create('mysql_prod', 'mysql').key({\n  host: '127.0.0.1',\n  port: 3306,\n  user: 'root',\n  password: 's3cr3t',\n  database: 'appdb',\n})\n```\n\n---\n\n## Schemas and Models\n\nSchemas define structure for collections/tables bound to a connection.\n\n### Define and register a schema\n\n```ts\nimport { schema } from '@neupgroup/mapper'\n\nconst sm = schema(conRegistry)\n\nsm.create('User')\n  .use({ connection: 'mysql_prod', collection: 'users' })\n  .setStructure({\n    id: 'string primary',\n    email: 'string unique',\n    name: 'string editable',\n    createdAt: 'date',\n    '?field': 'allow-undefined', // optional: permit fields not listed\n  })\n\nconst User = sm.use('User')\n```\n\n---\n\n## CRUD Operations\n\nAll operations return Promises and may throw on errors.\n\n### Insert\n\n```ts\nconst createdId = await User.add({\n  id: 'u_123',\n  email: 'alice@example.com',\n  name: 'Alice',\n  createdAt: new Date(),\n})\n```\n\n### Update\n\n```ts\nawait User.where(['id', 'u_123']).to({ name: 'Alice Cooper' }).updateOne()\n```\n\n### Delete\n\n```ts\nawait User.where(['id', 'u_123']).deleteOne()\n```\n\n### Fetch / Query\n\n```ts\nconst one = await User.where(['id', 'u_123']).getOne()\nconst many = await User.where('email', '%@example.com', 'like').get()\n```\n\n---\n\n## Schema Configuration Details\n\n- `primary`: marks primary key; used for updates/deletes.\n- `unique`: enforces uniqueness in supported backends.\n- `editable`: indicates fields commonly modified via UI.\n- `type`: one of `string`, `number`, `boolean`, `date`, `int`.\n- `?field`: enables accepting fields not defined in the schema.\n\n---\n\n## Error Handling\n\nWrap operations in `try/catch` and inspect known error shapes.\n\n```ts\ntry {\n  const user = await User.where(['id', 'u_404']).getOne()\n  if (!user) {\n    // handle not found gracefully\n  }\n} catch (err) {\n  if (err && typeof err === 'object' && 'code' in err) {\n    console.error('Database error code:', (err as any).code)\n  }\n  console.error('Unexpected error', err)\n}\n```\n\nRecommendations:\n- Validate required creds before initializing connections.\n- Prefer parameterized queries or ORM filters over string concatenation.\n- Log request IDs and timestamps for audit trails.\n\n---\n\n## Troubleshooting\n\n- \"Connection refused\": check host/port/firewall and credentials.\n- \"Authentication failed\": verify tokens/passwords and token scopes.\n- \"Timeout\": review network paths and optimize query.\n- \"Schema mismatch\": ensure field names/types match the backend.\n\n---\n\n## API Quick Reference\n\n- `parseConnectionsDsl(text)` \u2192 Map of connectionName \u2192 key/value creds\n- `toNormalizedConnections(map)` \u2192 Array of { name, type, key }\n- `connection()` \u2192 Connection registry (create/register/list/get)\n- `schema(connections?)` \u2192 Schema manager; define, register, and use schemas\n\n---\n\n## End-to-End Example\n\n```ts\nimport { parseConnectionsDsl, toNormalizedConnections, connection, schema } from '@neupgroup/mapper'\n\nconst text = await fs.promises.readFile('connections.dsl', 'utf8')\nconst map = parseConnectionsDsl(text)\nconst conns = toNormalizedConnections(map)\n\nconst conRegistry = connection()\nfor (const c of conns) conRegistry.register({ name: c.name, type: c.type, key: c.key })\n\nconst sm = schema(conRegistry)\nsm.create('Product')\n  .use({ connection: conns[0].name, collection: 'products' })\n  .setStructure({\n    id: 'string primary',\n    title: 'string',\n    price: 'number',\n    tags: 'string',\n  })\nconst Product = sm.use('Product')\n\nawait Product.add({ id: 'p_1', title: 'Widget', price: 9.99, tags: 'sale' })\nawait Product.where(['id', 'p_1']).to({ price: 7.99 }).updateOne()\nconst items = await Product.where('price', 10, '<').get()\nawait Product.where(['id', 'p_1']).deleteOne()\n```\n";
+export declare function markdownToHtml(md: string): string;
+export declare function getDocumentationHtml(): string;

package/dist/docs.js

@@ -0,0 +1,351 @@
+// Centralized documentation for @neupgroup/mapper.
+// Exports Markdown plus a minimal Markdown→HTML converter so apps can render
+// without a heavy dependency. Keep content comprehensive and up-to-date.
+export const documentationMd = `
+# Mapper Library Documentation
+
+Welcome to \`@neupgroup/mapper\`. This guide covers:
+- Installation
+- Configuring connections (DSL and UI)
+- Using connections in code
+- Creating schemas (ORM)
+- Configuring and using schemas
+- CRUD operations: insert, update, delete, fetch
+- Error handling and troubleshooting
+
+---
+
+## Installation
+
+- Install from npm:
+  \`npm install @neupgroup/mapper\`
+- In this workspace, the app depends on the library via \`workspace:*\`. Build the library when you update it:
+  \`cd library && npm run build\`
+- Import helpers:
+  \`import { parseConnectionsDsl, toNormalizedConnections } from '@neupgroup/mapper'\`
+
+---
+
+## Configure Connections
+
+You can configure connections in two ways:
+
+1) DSL File (recommended)
+2) UI Configure page (runtime setup)
+
+### 1) DSL Format
+
+Create \`connections.dsl\` at your project root:
+
+\`\`\`
+connections = [
+  mysql_prod: {
+    type: mysql
+    host: 127.0.0.1
+    port: 3306
+    user: root
+    password: "s3cr3t"
+    database: appdb
+  }
+
+  mongo_dev: {
+    type: mongodb
+    uri: "mongodb://127.0.0.1:27017"
+    database: devdb
+  }
+
+  firestore_local: {
+    type: firestore
+    projectId: my-project
+    applicationDefault: true
+  }
+
+  http_api: {
+    type: api
+    baseUrl: "https://api.example.com"
+    token: "abc123"
+  }
+]
+\`\`\`
+
+Notes:
+- \`type\` (or \`dbType\`) defaults to \`api\` if omitted.
+- Values can be unquoted or quoted; comments using \`#\` are ignored.
+
+Parse and normalize:
+
+\`\`\`ts
+import { parseConnectionsDsl, toNormalizedConnections } from '@neupgroup/mapper'
+
+const text = await fs.promises.readFile('connections.dsl', 'utf8')
+const envMap = parseConnectionsDsl(text)
+const connections = toNormalizedConnections(envMap)
+// connections: Array<{ name, type, key }>
+\`\`\`
+
+### 2) UI Configure Page
+
+- Go to \`/configure\` to define connections at runtime.
+- Use \"Generate collective env\" to produce \`connections.dsl\` from configured connections.
+- Download the file and commit it or load at startup.
+
+---
+
+## Use Connections in Code
+
+### Normalize and route by type
+
+\`\`\`ts
+import { parseConnectionsDsl, toNormalizedConnections } from '@neupgroup/mapper'
+import { connection, schema } from '@neupgroup/mapper'
+
+const text = await fs.promises.readFile('connections.dsl', 'utf8')
+const envMap = parseConnectionsDsl(text)
+const conns = toNormalizedConnections(envMap)
+
+// Register connections
+const conRegistry = connection()
+for (const c of conns) {
+  conRegistry.register({ name: c.name, type: c.type, key: c.key })
+}
+
+// Use with schemas
+const sm = schema(conRegistry)
+\`\`\`
+
+### Direct construction
+
+\`\`\`ts
+const conRegistry = connection()
+conRegistry.create('mysql_prod', 'mysql').key({
+  host: '127.0.0.1',
+  port: 3306,
+  user: 'root',
+  password: 's3cr3t',
+  database: 'appdb',
+})
+\`\`\`
+
+---
+
+## Schemas and Models
+
+Schemas define structure for collections/tables bound to a connection.
+
+### Define and register a schema
+
+\`\`\`ts
+import { schema } from '@neupgroup/mapper'
+
+const sm = schema(conRegistry)
+
+sm.create('User')
+  .use({ connection: 'mysql_prod', collection: 'users' })
+  .setStructure({
+    id: 'string primary',
+    email: 'string unique',
+    name: 'string editable',
+    createdAt: 'date',
+    '?field': 'allow-undefined', // optional: permit fields not listed
+  })
+
+const User = sm.use('User')
+\`\`\`
+
+---
+
+## CRUD Operations
+
+All operations return Promises and may throw on errors.
+
+### Insert
+
+\`\`\`ts
+const createdId = await User.add({
+  id: 'u_123',
+  email: 'alice@example.com',
+  name: 'Alice',
+  createdAt: new Date(),
+})
+\`\`\`
+
+### Update
+
+\`\`\`ts
+await User.where(['id', 'u_123']).to({ name: 'Alice Cooper' }).updateOne()
+\`\`\`
+
+### Delete
+
+\`\`\`ts
+await User.where(['id', 'u_123']).deleteOne()
+\`\`\`
+
+### Fetch / Query
+
+\`\`\`ts
+const one = await User.where(['id', 'u_123']).getOne()
+const many = await User.where('email', '%@example.com', 'like').get()
+\`\`\`
+
+---
+
+## Schema Configuration Details
+
+- \`primary\`: marks primary key; used for updates/deletes.
+- \`unique\`: enforces uniqueness in supported backends.
+- \`editable\`: indicates fields commonly modified via UI.
+- \`type\`: one of \`string\`, \`number\`, \`boolean\`, \`date\`, \`int\`.
+- \`?field\`: enables accepting fields not defined in the schema.
+
+---
+
+## Error Handling
+
+Wrap operations in \`try/catch\` and inspect known error shapes.
+
+\`\`\`ts
+try {
+  const user = await User.where(['id', 'u_404']).getOne()
+  if (!user) {
+    // handle not found gracefully
+  }
+} catch (err) {
+  if (err && typeof err === 'object' && 'code' in err) {
+    console.error('Database error code:', (err as any).code)
+  }
+  console.error('Unexpected error', err)
+}
+\`\`\`
+
+Recommendations:
+- Validate required creds before initializing connections.
+- Prefer parameterized queries or ORM filters over string concatenation.
+- Log request IDs and timestamps for audit trails.
+
+---
+
+## Troubleshooting
+
+- \"Connection refused\": check host/port/firewall and credentials.
+- \"Authentication failed\": verify tokens/passwords and token scopes.
+- \"Timeout\": review network paths and optimize query.
+- \"Schema mismatch\": ensure field names/types match the backend.
+
+---
+
+## API Quick Reference
+
+- \`parseConnectionsDsl(text)\` → Map of connectionName → key/value creds
+- \`toNormalizedConnections(map)\` → Array of { name, type, key }
+- \`connection()\` → Connection registry (create/register/list/get)
+- \`schema(connections?)\` → Schema manager; define, register, and use schemas
+
+---
+
+## End-to-End Example
+
+\`\`\`ts
+import { parseConnectionsDsl, toNormalizedConnections, connection, schema } from '@neupgroup/mapper'
+
+const text = await fs.promises.readFile('connections.dsl', 'utf8')
+const map = parseConnectionsDsl(text)
+const conns = toNormalizedConnections(map)
+
+const conRegistry = connection()
+for (const c of conns) conRegistry.register({ name: c.name, type: c.type, key: c.key })
+
+const sm = schema(conRegistry)
+sm.create('Product')
+  .use({ connection: conns[0].name, collection: 'products' })
+  .setStructure({
+    id: 'string primary',
+    title: 'string',
+    price: 'number',
+    tags: 'string',
+  })
+const Product = sm.use('Product')
+
+await Product.add({ id: 'p_1', title: 'Widget', price: 9.99, tags: 'sale' })
+await Product.where(['id', 'p_1']).to({ price: 7.99 }).updateOne()
+const items = await Product.where('price', 10, '<').get()
+await Product.where(['id', 'p_1']).deleteOne()
+\`\`\`
+`;
+// Minimal Markdown → HTML converter (headings, lists, code fences, inline code, paragraphs)
+export function markdownToHtml(md) {
+    const lines = md.split(/\r?\n/);
+    let html = [];
+    let inCode = false;
+    let codeBuf = [];
+    function escapeHtml(s) {
+        return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    }
+    function inline(s) {
+        s = s.replace(/`([^`]+)`/g, (_m, g1) => `<code>${escapeHtml(g1)}</code>`);
+        s = s.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+        s = s.replace(/\*([^*]+)\*/g, '<em>$1</em>');
+        s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+        return s;
+    }
+    function flushParagraph(buf) {
+        const text = buf.join(' ').trim();
+        if (!text)
+            return;
+        html.push(`<p>${inline(escapeHtml(text))}</p>`);
+        buf.length = 0;
+    }
+    let paraBuf = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim().startsWith('```')) {
+            if (inCode) {
+                html.push(`<pre><code>${escapeHtml(codeBuf.join('\n'))}</code></pre>`);
+                codeBuf = [];
+                inCode = false;
+            }
+            else {
+                flushParagraph(paraBuf);
+                inCode = true;
+            }
+            continue;
+        }
+        if (inCode) {
+            codeBuf.push(line);
+            continue;
+        }
+        const hMatch = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (hMatch) {
+            flushParagraph(paraBuf);
+            const level = hMatch[1].length;
+            const content = hMatch[2];
+            html.push(`<h${level}>${inline(escapeHtml(content))}</h${level}>`);
+            continue;
+        }
+        if (/^\s*[-*]\s+/.test(line)) {
+            flushParagraph(paraBuf);
+            let ulItems = [];
+            ulItems.push(line.replace(/^\s*[-*]\s+/, ''));
+            while (i + 1 < lines.length && /^\s*[-*]\s+/.test(lines[i + 1])) {
+                i++;
+                ulItems.push(lines[i].replace(/^\s*[-*]\s+/, ''));
+            }
+            const lis = ulItems.map(item => `<li>${inline(escapeHtml(item))}</li>`).join('');
+            html.push(`<ul>${lis}</ul>`);
+            continue;
+        }
+        if (/^\s*$/.test(line)) {
+            flushParagraph(paraBuf);
+            continue;
+        }
+        paraBuf.push(line);
+    }
+    if (inCode) {
+        html.push(`<pre><code>${codeBuf.map(s => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')).join('\n')}</code></pre>`);
+    }
+    flushParagraph(paraBuf);
+    return html.join('\n');
+}
+export function getDocumentationHtml() {
+    return markdownToHtml(documentationMd);
+}

package/dist/env.d.ts

@@ -0,0 +1,25 @@
+export type EnvDslConnections = Record<string, Record<string, string>>;
+/**
+ * Parse a simple DSL of the form:
+ * connections = [
+ *   connectionName = [
+ *     key: value,
+ *     key2: "value2",
+ *   ],
+ *   other = [
+ *     type: SQL,
+ *     host: localhost,
+ *   ]
+ * ]
+ */
+export declare function parseConnectionsDsl(text: string): EnvDslConnections;
+export type NormalizedConnection = {
+    name: string;
+    type: 'mysql' | 'sql' | 'firestore' | 'mongodb' | 'api';
+    key: Record<string, any>;
+};
+/**
+ * Convert DSL map to normalized connections compatible with library Connections.
+ * If no explicit type is provided, defaults to 'api'.
+ */
+export declare function toNormalizedConnections(map: EnvDslConnections): NormalizedConnection[];