hola-server 1.0.11 → 3.0.0

package/README.md

@@ -1 +1,382 @@
-# This is a meta programming framework used to build nodejs restful api
+# Hola Server
+
+A meta-programming framework for building RESTful APIs with **Bun + Elysia + MongoDB**. Define entity schemas declaratively and get fully-featured CRUD APIs with built-in authentication, role-based access control, file handling, and vector search — all out of the box.
+
+## ✨ Features
+
+- **Meta-Driven CRUD** — Define entity schemas with metadata, get full RESTful APIs automatically
+- **Role-Based Access Control** — Fine-grained permissions per entity and operation (`admin:*`, `user:r`, `editor:cru`)
+- **JWT Authentication** — Access + refresh token flow with hybrid delivery (cookies & Authorization header)
+- **Type System** — 20+ built-in types with extensible validation and conversion
+- **Schema Validation** — Auto-generated TypeBox schemas for request body validation
+- **File Handling** — Built-in GridFS integration for file uploads and streaming
+- **Vector Search** — SQLite-based vector similarity search via `sqlite-vec` for AI applications
+- **Entity Relationships** — References with cascade/keep delete behavior and ref validation
+- **Lifecycle Hooks** — Before/after hooks for create, update, clone, delete, and read operations
+- **Query Building** — Advanced search, filtering, comparison operators, and pagination
+- **Environment Config** — Configuration loader with environment-specific files (dev/test/prod)
+- **Comprehensive Testing** — 25 test files covering core, database, entity, and cleanup
+
+## 📦 Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Runtime | [Bun](https://bun.sh) |
+| HTTP Framework | [Elysia](https://elysiajs.com) v1.2+ |
+| Database | [MongoDB](https://www.mongodb.com) 6.x |
+| File Storage | MongoDB GridFS |
+| Vector Search | [sqlite-vec](https://github.com/asg017/sqlite-vec) + better-sqlite3 |
+| Auth | [@elysiajs/jwt](https://www.npmjs.com/package/@elysiajs/jwt) |
+| Language | TypeScript 5.7+ |
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+bun install
+```
+
+### 1. Define an Entity
+
+```typescript
+import { init_router } from "hola-server";
+
+export const userRouter = init_router({
+  collection: "user",
+  primary_keys: ["email"],
+  ref_label: "name",
+
+  creatable: true,
+  readable: true,
+  updatable: true,
+  deleteable: true,
+
+  fields: [
+    { name: "name", type: "string", required: true },
+    { name: "email", type: "string", required: true },
+    { name: "age", type: "uint" },
+    { name: "role", ref: "role" },
+    { name: "avatar", type: "file" },
+  ],
+
+  roles: ["admin:*", "user:r", "editor:cru"],
+});
+```
+
+### 2. Start the Server
+
+```typescript
+import { Elysia } from "elysia";
+import { plugins, db, meta } from "hola-server";
+import { userRouter } from "./router/user.js";
+
+const app = new Elysia()
+  .use(plugins.holaCors({ origin: ["http://localhost:5173"] }))
+  .use(plugins.holaBody({ limit: "10mb" }))
+  .use(plugins.holaAuth({ secret: process.env.JWT_SECRET! }))
+  .use(plugins.holaError())
+  .use(userRouter)
+  .onStart(async () => {
+    await db.get_db();
+    meta.validate_all_metas();
+    console.log("✓ Server ready on port 3000");
+  })
+  .listen(3000);
+```
+
+## 📡 API Endpoints
+
+Each entity router automatically generates these endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/{entity}` | Simple list with query params |
+| `POST` | `/{entity}/list` | List entities (full query: filter, sort, paginate) |
+| `GET` | `/{entity}/:id` | Get single entity by ID |
+| `POST` | `/{entity}` | Create entity |
+| `PUT` | `/{entity}/:id` | Update entity |
+| `DELETE` | `/{entity}/:id` | Delete entity |
+| `GET` | `/{entity}/meta` | Get entity metadata and permissions |
+| `GET` | `/{entity}/ref` | Get reference labels |
+| `POST` | `/{entity}/:id/clone` | Clone entity (if cloneable) |
+
+## 🏗 Entity Metadata
+
+### Field Definition
+
+```typescript
+interface FieldDefinition {
+  name: string;        // Field name
+  type?: string;       // Type for validation/conversion (default: "string")
+  required?: boolean;  // Required on create
+  default?: FieldValue;// Default value
+  ref?: string;        // Reference to another entity (collection name)
+  link?: string;       // Link to another entity
+  delete?: "keep" | "cascade"; // Ref delete behavior
+  create?: boolean;    // Include in create operation
+  list?: boolean;      // Include in list response
+  search?: boolean;    // Enable as search field
+  update?: boolean;    // Include in update operation
+  clone?: boolean;     // Include in clone operation
+  sys?: boolean;       // System field (auto-managed)
+  secure?: boolean;    // Exclude from client responses
+  view?: string;       // View-based visibility
+  role?: string | string[]; // Role-based field visibility
+}
+```
+
+### Built-in Types
+
+| Category | Types |
+|----------|-------|
+| **String** | `string`, `lstr`, `text`, `enum`, `email`, `url`, `ip` |
+| **Numeric** | `number`, `int`, `uint`, `float`, `ufloat`, `decimal`, `percentage`, `currency` |
+| **Boolean** | `boolean` |
+| **Date/Time** | `date`, `datetime` |
+| **Security** | `password` (bcrypt hashed), `secret` (AES-256 encrypted) |
+| **Other** | `file`, `array`, `obj`, `json`, `log_category` |
+
+Custom types can be registered via `register_type()`.
+
+### Operation Flags
+
+```typescript
+{
+  creatable: true,   // Enable POST endpoint
+  readable: true,    // Enable GET endpoints
+  updatable: true,   // Enable PUT endpoint
+  deleteable: true,  // Enable DELETE endpoint
+  cloneable: true,   // Enable clone endpoint
+  importable: true,  // Enable bulk import
+}
+```
+
+### Role Configuration
+
+Format: `role_name:permissions` or `role_name:permissions:view`
+
+```typescript
+roles: [
+  "admin:*",       // Admin can do everything
+  "user:r",        // User can only read
+  "editor:cru",    // Editor can create/read/update
+  "viewer:r:basic" // Viewer can read with "basic" view only
+]
+```
+
+### Lifecycle Hooks
+
+```typescript
+init_router({
+  collection: "order",
+  // ...fields and options...
+
+  before_create: async ({ entity, data }) => { /* validate before insert */ },
+  create: async ({ entity, data }) => { /* custom create logic */ },
+  after_create: async ({ entity, data }) => { /* post-create side effects */ },
+
+  before_update: async ({ id, entity, data }) => { /* pre-update checks */ },
+  update: async ({ id, entity, data }) => { /* custom update logic */ },
+  after_update: async ({ id, entity, data }) => { /* post-update actions */ },
+
+  before_delete: async ({ entity, ids }) => { /* pre-delete validation */ },
+  after_delete: async ({ entity, ids }) => { /* cleanup after delete */ },
+
+  after_read: async ({ id, entity, result }) => { /* transform read results */ },
+  list_query: async ({ entity, query }) => { /* modify list queries */ },
+
+  route: (router, meta) => { /* add custom routes */ },
+});
+```
+
+## 🔌 Plugins
+
+```typescript
+import { plugins } from "hola-server";
+
+// CORS with allowed origins
+app.use(plugins.holaCors({ origin: ["http://localhost:5173"] }));
+
+// Request body parsing with size limit
+app.use(plugins.holaBody({ limit: "10mb" }));
+
+// JWT auth with access + refresh tokens
+app.use(plugins.holaAuth({
+  secret: "your-secret",
+  accessExpiry: "15m",     // default
+  refreshExpiry: "7d",     // default
+  excludeUrls: ["/health", /^\/public/],
+}));
+
+// Auth routes (POST /auth/refresh, POST /auth/logout)
+app.use(plugins.holaAuthRoutes());
+
+// Global error handling
+app.use(plugins.holaError());
+```
+
+## 🗄 Database
+
+```typescript
+import { db } from "hola-server";
+
+// Direct MongoDB access
+const database = await db.get_db();
+const users = await database.collection("user").find({}).toArray();
+
+// Entity-level operations
+const entity = new db.Entity("user");
+await entity.create_entity(data, "*");
+await entity.read_entity(id, "*", "*");
+await entity.update_entity(id, updates, "*");
+await entity.delete_entity([id]);
+await entity.list_entity(queryParams, query, searchParams, role);
+```
+
+## 📁 File Storage (GridFS)
+
+```typescript
+import { db } from "hola-server";
+
+// Save file from buffer (FormData uploads)
+await db.save_file_from_buffer("avatars", "user_123.png", buffer);
+
+// Read file
+const fileBuffer = await db.read_file("avatars", "user_123.png");
+
+// Stream file
+const stream = await db.read_file_stream("avatars", "user_123.png");
+
+// Delete file
+await db.delete_file("avatars", "user_123.png");
+```
+
+## 🔍 Vector Search
+
+SQLite-based vector similarity search for AI/embedding applications:
+
+```typescript
+import { VectorStore, initVectorStore } from "hola-server";
+
+const store = await initVectorStore({
+  dbPath: "./data/vectors.db",
+  dimensions: 1536,
+  tableName: "embeddings",
+});
+
+// Insert vectors with metadata
+await store.insert("doc_1", embedding, { category: "article" });
+await store.insertBatch(records);
+
+// Search similar vectors
+const results = await store.search(queryEmbedding, 10, { category: "article" });
+// => [{ id, distance, score, metadata }]
+
+// Manage vectors
+await store.delete("doc_1");
+await store.deleteByFilter({ category: "old" });
+const count = await store.count();
+```
+
+## ⚙️ Configuration
+
+### Environment-Based Config
+
+```typescript
+import { config } from "hola-server";
+
+const appConfig = await config.load_config(__dirname + "/config");
+// Loads config/dev.ts, config/test.ts, or config/prod.ts based on NODE_ENV
+```
+
+### Settings
+
+```typescript
+import { init_settings } from "hola-server";
+
+init_settings({
+  mongo: { url: "mongodb://localhost:27017/myapp", pool: 10 },
+  encrypt: { key: "my-encryption-key" },
+  roles: [{ name: "admin", root: true }, { name: "user" }],
+  server: {
+    service_port: 8088,
+    client_web_url: ["http://localhost:5173"],
+    keep_session: true,
+    check_user: true,
+    exclude_urls: ["/"],
+    session: { cookie_max_age: 86400000, secret: "session-secret" },
+    threshold: { max_download_size: 5000, body_limit: "10mb", default_list_limit: 1000 },
+    routes: ["router"],
+  },
+  axios: { retry: 3, retry_delay: 1000, proxy: null },
+  log: { col_log: "log", log_level: 0, save_db: true },
+});
+```
+
+## 🧰 Core Utilities
+
+```typescript
+import { array, date, validate, encrypt, random, bash, file, obj, number, lhs } from "hola-server";
+
+// Array utilities
+array.unique([1, 2, 2, 3]); // [1, 2, 3]
+
+// Encryption
+const hashed = encrypt_pwd("password");
+const encrypted = encrypt_secret("api-key");
+const decrypted = decrypt_secret(encrypted);
+
+// And more: date formatting, validation, bash execution, file I/O, etc.
+```
+
+## 🧪 Testing
+
+```bash
+bun test
+```
+
+25 test files covering:
+- **Core**: array, chart, date, encrypt, file, lhs, meta, number, obj, random, thread, type, validate
+- **Database**: connection, operations, entity class, GridFS
+- **Entity CRUD**: create, read, update, delete, clone, ref-filter
+
+## 📂 Project Structure
+
+```
+hola-server/
+├── src/
+│   ├── index.ts          # Public API entry point
+│   ├── setting.ts        # Application settings
+│   ├── config/           # Environment-based config loader
+│   ├── core/             # Core utilities (16 modules)
+│   │   ├── meta.ts       # Entity metadata & lifecycle hooks
+│   │   ├── type.ts       # Type system & validation
+│   │   ├── role.ts       # Role-based access control
+│   │   ├── encrypt.ts    # Password hashing & AES encryption
+│   │   └── ...           # array, bash, chart, date, file, etc.
+│   ├── db/               # Database layer
+│   │   ├── db.ts         # MongoDB connection & helpers
+│   │   ├── entity.ts     # Entity CRUD operations
+│   │   └── gridfs.ts     # GridFS file storage
+│   ├── meta/             # Meta programming
+│   │   ├── router.ts     # Auto RESTful route generation
+│   │   └── schema.ts     # TypeBox schema generation
+│   ├── plugins/          # Elysia plugins
+│   │   ├── auth.ts       # JWT authentication
+│   │   ├── cors.ts       # CORS configuration
+│   │   ├── body.ts       # Body parser
+│   │   └── error.ts      # Error handling
+│   ├── errors/           # Error classes (auth, http, validation)
+│   ├── http/             # HTTP status codes
+│   └── tool/             # Tools
+│       ├── gen_i18n.ts   # i18n key generation
+│       └── vector_store.ts # Vector similarity search
+├── test/                 # Test suite (25 test files)
+├── package.json
+└── tsconfig.json
+```
+
+## 📄 License
+
+ISC

package/dist/config/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Configuration loader for environment-based settings.
+ * @module config
+ */
+export interface AppConfig {
+    /** Server port */
+    port: number;
+    /** JWT configuration */
+    jwt: {
+        secret: string;
+        accessExpiry: string;
+        refreshExpiry: string;
+    };
+    /** CORS configuration */
+    cors: {
+        origin: string[] | true;
+        credentials?: boolean;
+    };
+    /** Body parser configuration */
+    body: {
+        limit: string | number;
+    };
+    /** Database configuration */
+    db: {
+        url: string;
+    };
+}
+/**
+ * Load configuration from environment-specific file.
+ * Looks for config files in the specified directory based on NODE_ENV.
+ *
+ * @param config_dir Directory containing config files (dev.ts, test.ts, prod.ts)
+ * @returns Promise resolving to AppConfig
+ *
+ * @example
+ * ```typescript
+ * const config = await load_config(__dirname + '/config');
+ * ```
+ */
+export declare const load_config: (config_dir: string) => Promise<AppConfig>;
+/**
+ * Create a base config with common defaults.
+ * Use this as a starting point for environment configs.
+ */
+export declare const create_base_config: (overrides?: Partial<AppConfig>) => AppConfig;
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,SAAS;IACtB,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,GAAG,EAAE;QACD,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,yBAAyB;IACzB,IAAI,EAAE;QACF,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QACxB,WAAW,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,gCAAgC;IAChC,IAAI,EAAE;QACF,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;KAC1B,CAAC;IACF,6BAA6B;IAC7B,EAAE,EAAE;QACA,GAAG,EAAE,MAAM,CAAC;KACf,CAAC;CACL;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,GAAU,YAAY,MAAM,KAAG,OAAO,CAAC,SAAS,CAUvE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,YAAW,OAAO,CAAC,SAAS,CAAM,KAAG,SAsBtE,CAAC"}

package/dist/config/index.js

@@ -0,0 +1,55 @@
+/**
+ * Configuration loader for environment-based settings.
+ * @module config
+ */
+/**
+ * Load configuration from environment-specific file.
+ * Looks for config files in the specified directory based on NODE_ENV.
+ *
+ * @param config_dir Directory containing config files (dev.ts, test.ts, prod.ts)
+ * @returns Promise resolving to AppConfig
+ *
+ * @example
+ * ```typescript
+ * const config = await load_config(__dirname + '/config');
+ * ```
+ */
+export const load_config = async (config_dir) => {
+    const env = process.env.NODE_ENV || 'dev';
+    const config_path = `${config_dir}/${env}`;
+    try {
+        const module = await import(config_path);
+        return module.default;
+    }
+    catch (error) {
+        throw new Error(`Failed to load config for environment '${env}' from ${config_path}: ${error}`);
+    }
+};
+/**
+ * Create a base config with common defaults.
+ * Use this as a starting point for environment configs.
+ */
+export const create_base_config = (overrides = {}) => ({
+    port: 3000,
+    jwt: {
+        secret: 'change-this-in-production',
+        accessExpiry: '15m',
+        refreshExpiry: '7d',
+        ...overrides.jwt
+    },
+    cors: {
+        origin: ['http://localhost:5173'],
+        credentials: true,
+        ...overrides.cors
+    },
+    body: {
+        limit: '10mb',
+        ...overrides.body
+    },
+    db: {
+        url: 'mongodb://localhost:27017/hola',
+        ...overrides.db
+    },
+    ...overrides
+});
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0BH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,UAAkB,EAAsB,EAAE;IACxE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC1C,MAAM,WAAW,GAAG,GAAG,UAAU,IAAI,GAAG,EAAE,CAAC;IAE3C,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QACzC,OAAO,MAAM,CAAC,OAAoB,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,0CAA0C,GAAG,UAAU,WAAW,KAAK,KAAK,EAAE,CAAC,CAAC;IACpG,CAAC;AACL,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,YAAgC,EAAE,EAAa,EAAE,CAAC,CAAC;IAClF,IAAI,EAAE,IAAI;IACV,GAAG,EAAE;QACD,MAAM,EAAE,2BAA2B;QACnC,YAAY,EAAE,KAAK;QACnB,aAAa,EAAE,IAAI;QACnB,GAAG,SAAS,CAAC,GAAG;KACnB;IACD,IAAI,EAAE;QACF,MAAM,EAAE,CAAC,uBAAuB,CAAC;QACjC,WAAW,EAAE,IAAI;QACjB,GAAG,SAAS,CAAC,IAAI;KACpB;IACD,IAAI,EAAE;QACF,KAAK,EAAE,MAAM;QACb,GAAG,SAAS,CAAC,IAAI;KACpB;IACD,EAAE,EAAE;QACA,GAAG,EAAE,gCAAgC;QACrC,GAAG,SAAS,CAAC,EAAE;KAClB;IACD,GAAG,SAAS;CACf,CAAC,CAAC"}

package/dist/core/array.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Array manipulation utility functions.
+ * @module core/array
+ */
+/** Shuffle array elements randomly in place. */
+export declare const shuffle: <T>(arr: T[]) => void;
+/** Remove elements from array by matching field value. */
+export declare const remove_element: <T, K extends keyof T>(array: T[], field: K, value: T[K]) => void;
+export declare const pop_n: <T>(array: T[], n: number) => T[] | undefined;
+export declare const shift_n: <T>(array: T[], n: number) => T[] | undefined;
+/** Calculate sum of number array. */
+export declare const sum: (arr: number[]) => number;
+/** Calculate average of number array. */
+export declare const avg: (arr: number[]) => number;
+/** Convert array of objects to key-value object. */
+export declare const map_array_to_obj: <T, K extends keyof T, V extends keyof T>(arr: T[], key_attr: K, value_attr: V) => Record<string, T[V]>;
+/** Sort array of objects by attribute. */
+export declare const sort_by_attr: <T extends Record<string, number>>(arr: T[], attr: keyof T, desc?: boolean) => T[];
+export declare const sort_desc: <T extends Record<string, number>>(arr: T[], attr: keyof T) => T[];
+export declare const sort_asc: <T extends Record<string, number>>(arr: T[], attr: keyof T) => T[];
+/** Sort array by predefined key sequence. */
+export declare const sort_by_key_seq: <T, K extends keyof T>(arr: T[], attr: K, keys: T[K][]) => T[];
+/** Create cartesian product of two object arrays. */
+export declare const combine: <T extends object, U extends object>(arr1: T[], arr2: U[]) => (T & U)[];
+/** Remove duplicate elements from array. */
+export declare const unique: <T>(array: T[]) => T[];
+//# sourceMappingURL=array.d.ts.map

package/dist/core/array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/core/array.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,gDAAgD;AAChD,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,KAAK,CAAC,EAAE,KAAG,IAKrC,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,KAAG,IAIxF,CAAC;AAaF,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,MAAM,KAAG,CAAC,EAAE,GAAG,SAAuC,CAAC;AAC/F,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,MAAM,KAAG,CAAC,EAAE,GAAG,SAAyC,CAAC;AAEnG,qCAAqC;AACrC,eAAO,MAAM,GAAG,GAAI,KAAK,MAAM,EAAE,KAAG,MAAiE,CAAC;AAEtG,yCAAyC;AACzC,eAAO,MAAM,GAAG,GAAI,KAAK,MAAM,EAAE,KAAG,MAAuE,CAAC;AAE5G,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,UAAU,CAAC,EAAE,YAAY,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAEnI,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,MAAM,CAAC,EAAE,OAAM,OAAe,KAAG,CAAC,EAGhH,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,MAAM,CAAC,KAAG,CAAC,EAAmC,CAAC;AAC3H,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,MAAM,CAAC,KAAG,CAAC,EAAoC,CAAC;AAE3H,6CAA6C;AAC7C,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,KAAG,CAAC,EAGxF,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,KAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAEzF,CAAC;AAEF,4CAA4C;AAC5C,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,KAAG,CAAC,EAMvC,CAAC"}

package/dist/core/array.js

@@ -0,0 +1,66 @@
+/**
+ * Array manipulation utility functions.
+ * @module core/array
+ */
+import { round_to_fixed2 } from './number.js';
+/** Shuffle array elements randomly in place. */
+export const shuffle = (arr) => {
+    for (let i = arr.length; i; i--) {
+        const j = Math.floor(Math.random() * i);
+        [arr[i - 1], arr[j]] = [arr[j], arr[i - 1]];
+    }
+};
+/** Remove elements from array by matching field value. */
+export const remove_element = (array, field, value) => {
+    for (let i = array.length - 1; i >= 0; --i) {
+        if (array[i][field] == value)
+            array.splice(i, 1);
+    }
+};
+/** Extract n elements from array using specified method. */
+const extract_n = (array, n, method) => {
+    const result = [];
+    while (result.length < n) {
+        const ele = array[method]();
+        if (ele !== undefined)
+            result.push(ele);
+        else
+            break;
+    }
+    return result.length > 0 ? result : undefined;
+};
+export const pop_n = (array, n) => extract_n(array, n, 'pop');
+export const shift_n = (array, n) => extract_n(array, n, 'shift');
+/** Calculate sum of number array. */
+export const sum = (arr) => round_to_fixed2(arr.reduce((pre, cur) => pre + cur, 0));
+/** Calculate average of number array. */
+export const avg = (arr) => arr.length === 0 ? 0 : round_to_fixed2(sum(arr) / arr.length);
+/** Convert array of objects to key-value object. */
+export const map_array_to_obj = (arr, key_attr, value_attr) => {
+    return arr.reduce((obj, el) => ({ ...obj, [String(el[key_attr])]: el[value_attr] }), {});
+};
+/** Sort array of objects by attribute. */
+export const sort_by_attr = (arr, attr, desc = false) => {
+    arr.sort((a, b) => desc ? b[attr] - a[attr] : a[attr] - b[attr]);
+    return arr;
+};
+export const sort_desc = (arr, attr) => sort_by_attr(arr, attr, true);
+export const sort_asc = (arr, attr) => sort_by_attr(arr, attr, false);
+/** Sort array by predefined key sequence. */
+export const sort_by_key_seq = (arr, attr, keys) => {
+    arr.sort((a, b) => keys.indexOf(a[attr]) - keys.indexOf(b[attr]));
+    return arr;
+};
+/** Create cartesian product of two object arrays. */
+export const combine = (arr1, arr2) => {
+    return arr1.flatMap(obj1 => arr2.map(obj2 => ({ ...obj1, ...obj2 })));
+};
+/** Remove duplicate elements from array. */
+export const unique = (array) => {
+    const seen = new Map();
+    return array.filter(value => {
+        const key = JSON.stringify(value);
+        return seen.has(key) ? false : (seen.set(key, true), true);
+    });
+};
+//# sourceMappingURL=array.js.map

package/dist/core/array.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.js","sourceRoot":"","sources":["../../src/core/array.ts"],"names":[],"mappings":"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"}

package/dist/core/bash.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bash command execution and SSH utility functions.
+ * @module core/bash
+ */
+/** Serializable log value types. */
+export type LogValue = string | number | boolean | null | undefined | LogValue[] | {
+    [key: string]: LogValue;
+};
+export type LogExtra = Record<string, LogValue>;
+export interface Host {
+    name: string;
+    ip: string;
+    port: number;
+    user: string;
+    auth: string;
+}
+export interface CommandResult {
+    stdout: string;
+    err?: string;
+}
+export interface SystemAttribute {
+    name: string;
+    cmd: string;
+}
+/** Run command on local host. */
+export declare const run_local_cmd: (cmd: string, log_extra?: LogExtra) => Promise<CommandResult>;
+/** Run simple command locally and get trimmed result. */
+export declare const run_simple_local_cmd: (cmd: string, log_extra?: LogExtra) => Promise<string | null>;
+/** Run script on remote host via SSH. */
+export declare const run_script: (host: Host, script: string, log_extra?: LogExtra) => Promise<CommandResult>;
+/** Run script on remote host with file redirect to avoid progress bar issues. */
+export declare const run_script_extra: (host: Host, script: string, log_extra?: LogExtra) => Promise<CommandResult>;
+/** Run script file on remote host. */
+export declare const run_script_file: (host: Host, script_file: string, log_extra?: LogExtra) => Promise<CommandResult>;
+/** SCP remote file to local. */
+export declare const scp: (host: Host, remote_file: string, local_file: string, log_extra?: LogExtra) => Promise<CommandResult>;
+/** SCP local file to remote. */
+export declare const scpr: (host: Host, local_file: string, remote_file: string, log_extra?: LogExtra) => Promise<CommandResult>;
+/** Run simple command on remote host and get trimmed result. */
+export declare const run_simple_cmd: (host: Host, cmd: string, log_extra?: LogExtra) => Promise<string | null>;
+/** Extract info from stdout using regex pattern matching. */
+export declare const get_info: (stdout: string, key: string, log_extra?: LogExtra) => string[];
+/** Read key-value pairs from stdout. */
+export declare const read_key_value_line: (stdout: string, delimiter?: string, lines?: number[], config?: Record<string, boolean>, exclude_mode?: boolean) => Record<string, string>;
+/** Read structured lines into array of objects. */
+export declare const read_obj_line: (stdout: string, keys: string[], ignore?: number, delimiter?: string) => Record<string, string>[];
+/** Get multiple system attributes from remote host. */
+export declare const get_system_attributes: (host: Host, attrs: SystemAttribute[], log_extra?: LogExtra) => Promise<Record<string, string>>;
+/** Stop process on remote host if running. */
+export declare const stop_process: (host: Host, process_name: string, stop_cmd: string, using_full?: boolean, log_extra?: LogExtra) => Promise<boolean>;
+//# sourceMappingURL=bash.d.ts.map

package/dist/core/bash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../src/core/bash.ts"],"names":[],"mappings":"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"}