squilo 0.1.2

package/README.md

@@ -0,0 +1,88 @@
+# Squilo
+
+![npm version](https://img.shields.io/npm/v/squilo)
+![bun compatible](https://img.shields.io/badge/bun-v1.2.20%2B-blue)
+![license](https://img.shields.io/github/license/douglasdasilvasousa/squilo)
+
+Squilo is a Bun-first library for orchestrating SQL Server connections, authentication, and script execution with modern TypeScript patterns.
+
+## Getting Started
+
+### Initialize a Bun Project
+
+```bash
+bun init
+```
+
+### Add Squilo as a Production Dependency
+
+```bash
+bun add squilo
+```
+
+## Usage Example
+
+### Exportable Servers (Production, Dev, ...)
+
+```ts
+// src/server.ts
+import { Server } from "squilo";
+
+export const ProdServer = Server({
+  server: "prod-host",
+  port: 1433,
+  options: { encrypt: true }
+});
+
+export const DevServer = Server({
+  server: "localhost",
+  port: 1433,
+  options: { encrypt: false }
+});
+```
+
+### Exportable Authentications
+
+```ts
+// src/auth.ts
+import { UserAndPassword } from "squilo/pipes/auth/strategies";
+
+export const ProdAuth = UserAndPassword("prod_user", "prod_pass");
+export const DevAuth = UserAndPassword("sa", "your_dev_password");
+```
+
+### Create Scripts
+
+```ts
+// scripts/fixEmails.ts
+import { ProdServer } from "../src/server";
+import { ProdAuth } from "../src/auth";
+
+await ProdServer.Auth(ProdAuth)
+  .Connect(["db1", "db2"])
+  .Execute(async (transaction) => {
+    await transaction.request().query`
+      UPDATE Users SET Email = RTRIM(Email)
+    `;
+  });
+```
+
+### Run Scripts Using Bun
+
+```bash
+bun run scripts/fixEmails.ts
+```
+
+## Advanced Usage
+
+- Use `.Input()` to provide dynamic input for scripts
+- Use `.Retrieve()` to fetch results from databases
+- Use `.Output()` strategies to merge or format results
+
+## Reference
+
+See the [test suite](./test/) for more advanced usage and orchestration patterns.
+
+---
+
+This project was created using `bun init` in bun v1.2.20. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/biome.json

@@ -0,0 +1,34 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "squilo",
+  "version": "0.1.2",
+  "module": "index.ts",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/douglasdasilvasousa/Squilo.git"
+  },
+  "author": {
+    "name": "Douglas da Silva Sousa",
+    "email": "douglass.sousa@outlook.com.br"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./auth": "./src/pipes/auth/strategies/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:debug": "bun test --inspect"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.2.0",
+    "@faker-js/faker": "^9.9.0",
+    "@types/bun": "latest",
+    "@types/xlsx": "^0.0.36",
+    "testcontainers": "^11.5.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^3.7.1",
+    "@types/mssql": "^9.1.7",
+    "mssql": "^11.0.1",
+    "open": "^10.2.0",
+    "xlsx": "^0.18.5"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from  "./pipes/server"

package/src/pipes/auth/index.ts

@@ -0,0 +1,24 @@
+import type { config } from 'mssql';
+import type { ServerConfig } from "../server/types";
+import type { ConnectionOptions } from "../connect";
+import { Pool } from "../../pool";
+import { type ConnectionChain, Connect } from "../connect";
+
+export type AuthStrategy = (config: ServerConfig) => config;
+
+export type AuthenticationChain = {
+    Connect(database: string): ConnectionChain;
+    Connect(databases: string[], concurrent?: number): ConnectionChain;
+    Connect(options: ConnectionOptions, concurrent?: number): ConnectionChain;
+    Close(): Promise<void>;
+}
+
+export const Auth = (config: ServerConfig) => (strategy: AuthStrategy): AuthenticationChain => {
+    const configWithAuth = strategy(config);
+    const pool = Pool(configWithAuth);
+
+    return {
+        Connect: Connect(pool),
+        Close: () => pool.closeAll(),
+    }
+}

package/src/pipes/auth/strategies/index.ts

@@ -0,0 +1,2 @@
+export { UserAndPassword } from './userAndPassword';
+export { ActiveDirectoryAccessToken } from './msal'

package/src/pipes/auth/strategies/msal.ts

@@ -0,0 +1,133 @@
+import {
+    type AuthenticationResult,
+    type Configuration,
+    type ICachePlugin,
+    type InteractiveRequest,
+    LogLevel,
+    type NodeAuthOptions,
+    PublicClientApplication,
+    type TokenCache,
+    type TokenCacheContext,
+} from "@azure/msal-node";
+
+import * as path from "path";
+import type { ServerConfig } from "../../server/types";
+import type { AuthStrategy } from "..";
+import { cwd } from "process";
+
+const SCOPES = ["https://database.windows.net//.default"];
+
+const cacheAccess = (hash: string) => {
+    const cacheFilePath = path.join(cwd(), `${hash}.json`);
+
+    const before = async (cacheContext: TokenCacheContext) => {
+        try {
+            const cacheFile = await Bun.file(cacheFilePath).text();
+            cacheContext.tokenCache.deserialize(cacheFile);
+        } catch (err) {
+            await Bun.write(cacheFilePath, "");
+            cacheContext.tokenCache.deserialize("");
+        }
+    };
+
+    const after = async (cacheContext: TokenCacheContext) => {
+        if (cacheContext.cacheHasChanged) {
+            try {
+                await Bun.write(cacheFilePath, cacheContext.tokenCache.serialize());
+            } catch (err) {
+                console.error(err);
+            }
+        }
+    };
+
+    return {
+        beforeCacheAccess: before,
+        afterCacheAccess: after,
+    };
+};
+
+const msalConfig = (config: NodeAuthOptions, cachePlugin: ICachePlugin) => ({
+    auth: config,
+    cache: {
+        cachePlugin,
+    },
+    system: {
+        loggerOptions: {
+            loggerCallback(loglevel, message) {
+                console.log(message);
+            },
+            piiLoggingEnabled: false,
+            logLevel: LogLevel.Error,
+        },
+    },
+} as Configuration);
+
+export const GetToken = async (config: NodeAuthOptions) => {
+    const tenantId = config.authority?.replace("https://login.microsoftonline.com/", "");
+    const clientId = config.clientId;
+
+    const pca: PublicClientApplication = new PublicClientApplication(
+        msalConfig(config, cacheAccess(`${tenantId}-${clientId}`)),
+    );
+
+    const tokenCache: TokenCache = pca.getTokenCache();
+
+    async function getAccount() {
+        return await tokenCache.getAllAccounts();
+    }
+
+    const accounts = await getAccount();
+    let result: AuthenticationResult | null;
+
+    if (accounts.length > 0 && accounts[0]) {
+        result = await pca.acquireTokenSilent({
+            scopes: SCOPES,
+            account: accounts[0],
+        });
+
+        return result?.accessToken;
+    }
+
+    const interactiveRequest: InteractiveRequest = {
+        scopes: SCOPES,
+        openBrowser: async (url) => {
+            const { default: open } = await import("open");
+            open(url);
+        },
+        successTemplate: `
+            <html lang="HTML5">
+                <head>
+                    <title>Authentication Success</title>
+                </head>
+                <script>
+                    setTimeout(() => {
+                        window.close();
+                    }, 1000);
+                </script>
+                <body>
+                    <h1>Authentication Success</h1>
+                    <p>This window will be closed now</p>
+                </body>
+            </html>
+        `,
+    };
+
+    result = await pca.acquireTokenInteractive(interactiveRequest);
+
+    return result?.accessToken;
+};
+
+export const ActiveDirectoryAccessToken = async (config: NodeAuthOptions): Promise<AuthStrategy> => {
+    const accessToken = await GetToken(config);
+    return (config: ServerConfig) => {
+        return {
+            ...config,
+            authentication: {
+                type: 'azure-active-directory-access-token',
+                options: {
+                    token: accessToken
+                }
+            }
+        }
+    }
+}

package/src/pipes/auth/strategies/userAndPassword.ts

@@ -0,0 +1,10 @@
+import type { AuthStrategy } from ".."
+import type { ServerConfig } from "../../server/types"
+
+export const UserAndPassword = (username: string, password: string): AuthStrategy => (config: ServerConfig) => {
+    return {
+        ...config,
+        user: username,
+        password
+    }
+}

package/src/pipes/connect/index.ts

@@ -0,0 +1,78 @@
+import type { ConnectionPool, Transaction } from "mssql";
+import type { Pool } from "../../pool";
+import { type InputChain, Input } from "../input";
+import { Execute } from "../execute";
+import { type RetrieveChain, Retrieve } from "../retrieve";
+
+export type ConnectOverloads = {
+    (database: string): ConnectionChain;
+    (databases: string[], concurrent?: number): ConnectionChain;
+    (options: ConnectionOptions, concurrent?: number): ConnectionChain;
+}
+
+export type ConnectionOptions = {
+    database: string;
+    query: `SELECT${string}FROM${string}`;
+}
+
+export type DatabaseConnection = {
+    database: string;
+    connection: Promise<ConnectionPool>;
+}
+
+export type ConnectionChain = {
+    Execute(fn: (transaction: Transaction, database: string) => Promise<void>): Promise<void>;
+    Retrieve<TResult>(fn: (transaction: Transaction, database: string) => Promise<TResult>): RetrieveChain<TResult>;
+    Input<TParam>(fn: () => TParam): InputChain<TParam>;
+}
+
+export const Connect = (pool: Pool): ConnectOverloads => (param: string | string[] | ConnectionOptions, concurrent?: number): ConnectionChain => {    
+    let connections$: AsyncGenerator<DatabaseConnection[]>;
+    let databases$: Promise<string[]>;
+
+    async function *connections(databases$: Promise<string[]>, concurrent: number = Number.MAX_VALUE) {
+        const databases = await databases$;
+        
+        const databases_result_chunks = Array.from(
+            {length: Math.ceil(databases.length / concurrent)},
+            (_, i) => databases.slice(i * concurrent, (i + 1) * concurrent)
+        );
+
+        for (const databases_result_chunk of databases_result_chunks) {
+            yield databases_result_chunk.map(database => ({
+                database,
+                connection: pool.connect({ database })
+            }));
+        }
+    }
+
+    if (typeof param === 'string') {
+        databases$ = Promise.resolve([param]);
+    }
+
+    else if (Array.isArray(param)) {
+        databases$ = Promise.resolve(param);
+    }
+
+    else if (typeof param === 'object' && 'query' in param) {
+        databases$ = pool
+            .connect({ database: param.database, arrayRowMode: true })
+            .then(conn => conn
+                .request()
+                .query<string[]>(param.query)
+            )
+            .then(result => result.recordset.flat())
+    }
+
+    else {
+        throw new Error("Invalid parameter");
+    }
+
+    connections$ = connections(databases$, concurrent);
+
+    return {
+        Input: Input(connections$),
+        Execute: Execute(connections$, null),
+        Retrieve: Retrieve(connections$, null)
+    }
+  }

package/src/pipes/execute/index.ts

@@ -0,0 +1,29 @@
+import type { Transaction } from 'mssql';
+import type { DatabaseConnection } from "../connect";
+
+export const Execute = <TParam>(
+    connections$: AsyncGenerator<DatabaseConnection[]>, 
+    input: TParam
+) => {
+    return async (
+        fn: (transaction: Transaction, database: string, params: TParam) => Promise<void>
+    ): Promise<void> => {
+        const executeFn = async (dc: DatabaseConnection): Promise<void> => {
+            const opened = await dc.connection;
+            const transaction = opened.transaction()
+            try {
+                await transaction.begin();
+                await fn(transaction, dc.database, input);
+                await transaction.commit();
+            } 
+            catch (error) {
+                await transaction.rollback();
+            }
+        };
+
+        for await (const connectionBatch of connections$) {
+            const executions = connectionBatch.map(executeFn);
+            await Promise.allSettled(executions);
+        }
+    };
+};

package/src/pipes/index.ts

@@ -0,0 +1 @@
+export { Server } from './server/index'

package/src/pipes/input/index.ts

@@ -0,0 +1,19 @@
+import type { Transaction } from "mssql";
+import { Execute } from "../execute";
+import type { DatabaseConnection } from "../connect";
+import { Retrieve, type RetrieveChain } from "../retrieve";
+
+export type InputChain<TParam> = {
+    Execute(fn: (transaction: Transaction, database: string, params: TParam) => Promise<void>): Promise<void>;
+    Retrieve<TResult>(fn: (transaction: Transaction, database: string, params: TParam) => Promise<TResult>): RetrieveChain<TResult>;
+}
+
+export const Input = (connections: AsyncGenerator<DatabaseConnection[]>) => {
+    return <TParam>(fn: () => TParam): InputChain<TParam> => {
+        const params = fn();
+        return {
+            Execute: Execute(connections, params),
+            Retrieve: Retrieve(connections, params)
+        }
+    }
+}

package/src/pipes/output/index.ts

@@ -0,0 +1,4 @@
+export type OutputStrategy<TReturn, TOutput = void> = (data: ReadableStream<Record<string, TReturn>>) => Promise<TOutput>;
+
+export const Output = <TReturn, TOutput = void>(data: ReadableStream<Record<string, TReturn>>) => (strategy: OutputStrategy<TReturn, TOutput>): Promise<TOutput> => strategy(data);
+

package/src/pipes/output/strategies/console.ts

@@ -0,0 +1,7 @@
+import type { OutputStrategy } from '../index';
+
+export const ConsoleOutputStrategy = <TData>(): OutputStrategy<TData, void> => async (result) => {
+  for await (const data of result) {
+    console.log(data);
+  }
+};

package/src/pipes/output/strategies/index.ts

@@ -0,0 +1,4 @@
+export { MergeOutputStrategy } from './merge';
+export { ConsoleOutputStrategy } from './console';
+export { JsonOutputStrategy } from './json';
+export { XlsOutputStrategy } from './xls';

package/src/pipes/output/strategies/json.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { JsonOutputStrategy } from "./index";
+
+describe("JsonOutputStrategy", () => {
+  test("should format data as JSON with database keys", async () => {
+    const mockData = new ReadableStream({
+      start(controller) {
+        controller.enqueue({ "database1": [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }] });
+        controller.enqueue({ "database2": [{ id: 3, name: "Charlie" }] });
+        controller.close();
+      }
+    });
+
+    const strategy = JsonOutputStrategy();
+    const result = await strategy(mockData);
+    
+    expect(typeof result).toBe("object");
+    expect(result).toEqual({
+      "database1": [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }],
+      "database2": [{ id: 3, name: "Charlie" }]
+    });
+  });
+
+  test("should handle empty data", async () => {
+    const mockData = new ReadableStream({
+      start(controller) {
+        controller.enqueue({});
+        controller.close();
+      }
+    });
+
+    const strategy = JsonOutputStrategy();
+    const result = await strategy(mockData);
+    
+    expect(typeof result).toBe("object");
+    expect(result).toEqual({});
+  });
+});

package/src/pipes/output/strategies/json.ts

@@ -0,0 +1,9 @@
+import type { OutputStrategy } from '../index';
+
+export const JsonOutputStrategy = <TData>(): OutputStrategy<TData, Record<string, TData[]>> => async (result) => {
+  const data: Record<string, TData[]> = {};
+  for await (const item of result) {
+    Object.assign(data, item);
+  }
+  return data;
+};

package/src/pipes/output/strategies/merge.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { MergeOutputStrategy } from "./index";
+
+describe("MergeOutputStrategy", () => {
+  test("should merge array data from multiple sources", async () => {
+    const mockData = new ReadableStream({
+      start(controller) {
+        controller.enqueue({"database1": [1, 2, 3, 4, 5]});
+        controller.enqueue({"database2": [6, 7, 8, 9, 10]});
+        controller.close();
+      }
+    });
+
+    const strategy = MergeOutputStrategy<number[]>();
+    const result = await strategy(mockData);
+    expect(result).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+  });
+
+  test("should handle empty arrays", async () => {
+    const mockData = new ReadableStream({
+      start(controller) {
+        controller.enqueue({"database1": []});
+        controller.enqueue({"database2": []});
+        controller.close();
+      }
+    });
+
+    const strategy = MergeOutputStrategy<number[]>();
+    const result = await strategy(mockData);
+    
+    expect(result).toEqual([]);
+  });
+
+  test("should merge object arrays", async () => {
+    const mockData = new ReadableStream({
+      start(controller) {
+        controller.enqueue({"database1": [{ id: 1, name: "Alice" }]});
+        controller.enqueue({"database2": [{ id: 2, name: "Bob" }]});
+        controller.close();
+      }
+    });
+
+    const strategy = MergeOutputStrategy<{ id: number; name: string }[]>();
+    const result = await strategy(mockData);
+    
+    expect(result).toEqual([
+      { id: 1, name: "Alice" },
+      { id: 2, name: "Bob" }
+    ]);
+  });
+});

package/src/pipes/output/strategies/merge.ts

@@ -0,0 +1,11 @@
+import type { OutputStrategy } from '../index';
+
+export const MergeOutputStrategy = <TData extends Array<unknown>, TMerged = TData extends Array<infer TItem> ? TItem : TData>(): OutputStrategy<TData, TMerged[]> => async (result) => {
+  const data: TMerged[] = [];
+  for await (const item of result) {
+    Object.values(item).forEach((value) => {
+      data.push(...value as TMerged[]);
+    });
+  }
+  return data;
+};

package/src/pipes/output/strategies/xls.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { XlsOutputStrategy } from "./index";
+
+describe("XlsOutputStrategy", () => {
+  test("should generate XLS file with separate sheets", async () => {
+    const mockData = new ReadableStream({
+      start(controller) {
+        controller.enqueue({ 
+          "database1": [{ id: 1, name: "Alice", age: 30 }, { id: 2, name: "Bob", age: 25 }],
+          "database2": [{ id: 3, name: "Charlie", age: 35 }]
+        });
+        controller.close();
+      }
+    });
+
+    const testFile = "/tmp/test-separate.xlsx";
+    const strategy = XlsOutputStrategy(false, testFile);
+    await strategy(mockData);
+    
+    expect(await Bun.file(testFile).exists()).toBe(true);
+    
+    // Clean up
+    await Bun.file(testFile).delete();
+  });
+
+  test("should generate XLS file with combined sheet when unique=true", async () => {
+    const mockData = new ReadableStream({
+      start(controller) {
+        controller.enqueue({ 
+          "database1": [{ id: 1, name: "Alice", age: 30 }],
+          "database2": [{ id: 2, name: "Bob", age: 25 }]
+        });
+        controller.close();
+      }
+    });
+
+    const testFile = "/tmp/test-combined.xlsx";
+    const strategy = XlsOutputStrategy(true, testFile);
+    await strategy(mockData);
+    
+    expect(await Bun.file(testFile).exists()).toBe(true);
+    
+    // Clean up
+    await Bun.file(testFile).delete();
+  });
+
+  test("should create empty sheet when no data provided", async () => {
+    const mockData = new ReadableStream({
+      start(controller) {
+        controller.enqueue({});
+        controller.close();
+      }
+    });
+
+    const testFile = "/tmp/test-empty.xlsx";
+    const strategy = XlsOutputStrategy(false, testFile);
+    await strategy(mockData);
+    
+    expect(await Bun.file(testFile).exists()).toBe(true);
+    
+    // Clean up
+    await Bun.file(testFile).delete();
+  });
+});