@elaraai/east-node-io 0.0.1-beta.0

package/CLA.md

@@ -0,0 +1,26 @@
+# Contributor License Agreement
+
+This Contributor License Agreement ("Agreement") is entered into between Elara AI Pty Ltd ("Company") and you (the "Contributor").
+
+## Grant of Copyright License
+
+You hereby grant to the Company and to recipients of software distributed by the Company a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, distribute, and use Your Contributions and such derivative works.
+
+## Grant of Patent License
+
+You hereby grant to the Company and to recipients of software distributed by the Company a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer Your Contributions.
+
+## Relicensing Rights
+
+You grant the Company the right to license Your Contributions under any license terms, including but not limited to commercial licenses, in addition to the open source license under which the project is distributed.
+
+## Your Representations
+
+You represent that:
+- You are legally entitled to grant the above licenses
+- Each of Your Contributions is Your original creation
+- Your Contribution submissions include complete details of any third-party license or other restriction of which you are aware
+
+## Agreement
+
+By signing this Agreement through CLA Assistant or by submitting a Contribution, you accept and agree to the terms of this Agreement.

package/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing to East
+
+Thank you for your interest in contributing! We welcome contributions from the community.
+
+## Contributor License Agreement (CLA)
+
+Before we can accept your contribution, you must sign our Contributor License Agreement (CLA). This agreement gives Elara AI Pty Ltd the right to use and relicense your contributions, including under commercial licenses, while you retain ownership of your contribution.
+
+**Why do we require a CLA?**
+This project is dual-licensed under AGPL-3.0 and commercial licenses. The CLA allows us to offer commercial licenses to users who wish to use this software in proprietary applications.
+
+### Signing the CLA
+
+When you submit your first pull request, the CLA Assistant bot will automatically comment on your PR with a link to sign the CLA electronically. It only takes a minute, and you'll only need to sign it once.
+
+## Contributing Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+7. Sign the CLA when the bot prompts you
+
+## Questions?
+
+Contact us at support@elara.ai

package/README.md

@@ -0,0 +1,220 @@
+# East Node IO
+
+> I/O platform functions for the East language on Node.js
+
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE.md)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
+
+East Node IO provides type-safe I/O platform functions for [East](https://github.com/elaraai/east) programs running on Node.js, enabling database operations, cloud storage, file transfer, NoSQL operations, file format processing, and compression.
+
+## Features
+
+- **SQL Databases**: SQLite, PostgreSQL, MySQL with connection pooling
+- **Cloud Storage**: S3 and S3-compatible object storage (MinIO, etc.)
+- **File Transfer**: FTP and SFTP for legacy system integration
+- **NoSQL**: Redis caching and MongoDB document storage
+- **File Formats**: XLSX (Excel), CSV, and XML parsing and serialization
+- **Compression**: Gzip, Zip, and Tar compression and decompression
+- **Type Safety**: Full East type system integration
+- **Async I/O**: All operations use `implementAsync` for non-blocking I/O
+
+## Installation
+
+```bash
+npm install @elaraai/east-node-io
+```
+
+## Quick Start
+
+### SQL Database Query
+
+```typescript
+import { East, StringType, IntegerType, NullType } from "@elaraai/east";
+import { SQL } from "@elaraai/east-node-io";
+
+const getUserById = East.function([IntegerType], NullType, ($, userId) => {
+    const config = $.let({
+        host: "localhost",
+        port: 5432n,
+        database: "myapp",
+        user: "postgres",
+        password: "secret",
+        ssl: East.variant('none', null),
+        maxConnections: East.variant('none', null),
+    });
+
+    const conn = $.let(SQL.Postgres.connect(config));
+    $(SQL.Postgres.query(
+        conn,
+        "SELECT name FROM users WHERE id = $1",
+        [East.variant("Integer", userId)]
+    ));
+    $(SQL.Postgres.close(conn));
+
+    return $.return(null);
+});
+
+const compiled = East.compileAsync(getUserById.toIR(), SQL.Postgres.Implementation);
+await compiled(42n);
+```
+
+### S3 File Upload/Download
+
+```typescript
+import { Storage } from "@elaraai/east-node-io";
+import { East, StringType, BlobType } from "@elaraai/east";
+
+const uploadFile = East.function([StringType, BlobType], StringType, ($, filename, data) => {
+    const config = $.let({
+        region: "us-east-1",
+        bucket: "my-bucket",
+        accessKeyId: East.variant('none', null),
+        secretAccessKey: East.variant('none', null),
+        endpoint: East.variant('none', null),
+    });
+
+    $(Storage.S3.putObject(config, filename, data));
+    return Storage.S3.presignUrl(config, filename, 3600n);
+});
+
+const compiled = East.compileAsync(uploadFile.toIR(), Storage.S3.Implementation);
+const url = await compiled("report.pdf", pdfBlob);
+```
+
+### Redis Caching
+
+```typescript
+import { East, StringType, OptionType } from "@elaraai/east";
+import { NoSQL } from "@elaraai/east-node-io";
+
+const cacheGet = East.function([StringType], OptionType(StringType), ($, key) => {
+    const config = $.let({
+        host: "localhost",
+        port: 6379n,
+        password: East.variant('none', null),
+        db: East.variant('none', null),
+        keyPrefix: East.variant('none', null),
+    });
+
+    const conn = $.let(NoSQL.Redis.connect(config));
+    const value = $.let(NoSQL.Redis.get(conn, key));
+    $(NoSQL.Redis.close(conn));
+
+    return $.return(value);
+});
+
+const compiled = East.compileAsync(cacheGet.toIR(), NoSQL.Redis.Implementation);
+const cached = await compiled("user:42");  // some("...") or none
+```
+
+### File Format Processing
+
+```typescript
+import { Format } from "@elaraai/east-node-io";
+import { East, BlobType, IntegerType } from "@elaraai/east";
+
+// Read Excel files
+const countRows = East.function([BlobType], IntegerType, ($, xlsxBlob) => {
+    const options = $.let({
+        sheetName: East.variant('none', null),
+    });
+
+    const sheet = $.let(Format.XLSX.read(xlsxBlob, options));
+    return $.return(sheet.size());
+});
+
+const compiled = East.compile(countRows.toIR(), Format.XLSX.Implementation);
+const rowCount = compiled(xlsxBlob);  // 100n
+```
+
+## Platform Functions
+
+### SQL
+
+- **SQLite**: `connect`, `query`, `close`
+- **PostgreSQL**: `connect`, `query`, `close`
+- **MySQL**: `connect`, `query`, `close`
+
+### Storage
+
+- **S3**: `putObject`, `getObject`, `deleteObject`, `listObjects`, `presignUrl`
+
+### Transfer
+
+- **FTP**: `connect`, `put`, `get`, `list`, `delete`, `close`
+- **SFTP**: `connect`, `put`, `get`, `list`, `delete`, `close`
+
+### NoSQL
+
+- **Redis**: `connect`, `get`, `set`, `setex`, `del`, `close`
+- **MongoDB**: `connect`, `insertOne`, `findOne`, `find`, `updateOne`, `deleteOne`, `close`
+
+### Format
+
+- **XLSX**: `read`, `write`, `info` - Excel spreadsheet processing
+- **CSV**: `parse`, `serialize` - Comma-separated values with header support
+- **XML**: `parse`, `serialize` - XML document tree processing
+
+### Compression
+
+- **Gzip**: `compress`, `decompress` - Gzip compression (RFC 1952)
+- **Zip**: `compress`, `decompress` - ZIP archive creation and extraction
+- **Tar**: `create`, `extract` - TAR archive creation and extraction
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests (requires Docker)
+npm run test:integration
+
+# Start Docker services for development
+npm run dev:services
+
+# Stop Docker services
+npm run dev:services:down
+
+# Lint code
+npm run lint
+```
+
+## Testing
+
+Integration tests require Docker for running real databases and services:
+
+```bash
+# Start all services (PostgreSQL, MySQL, MongoDB, Redis, MinIO, FTP, SFTP)
+npm run dev:services
+
+# Run full integration test suite
+npm run test:integration
+
+# Stop all services
+npm run dev:services:down
+```
+
+## Documentation
+
+- [Usage Guide](USAGE.md)
+- [Development Standards](STANDARDS.md)
+- [Contributing Guidelines](CONTRIBUTING.md)
+- [License](LICENSE.md)
+
+## License
+
+Copyright (c) 2025 Elara AI Pty Ltd
+
+This project is licensed under the GNU Affero General Public License v3.0 - see the [LICENSE.md](LICENSE.md) file for details.
+
+## Dependencies
+
+- **SQL**: `better-sqlite3`, `pg`, `mysql2`
+- **Storage**: `@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`
+- **Transfer**: `basic-ftp`, `ssh2-sftp-client`
+- **NoSQL**: `ioredis`, `mongodb`
+- **Format**: `xlsx` for Excel file processing

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@elaraai/east-node-io",
+  "version": "0.0.1-beta.0",
+  "description": "I/O platform functions for the East language on Node.js",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "!dist/src/**/*.spec.*",
+    "README.md",
+    "LICENSE.md",
+    "CONTRIBUTING.md",
+    "CLA.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "package": "npm run build && mkdir -p .package && npm pack --pack-destination .package",
+    "prepublishOnly": "npm run lint && npm run test",
+    "test": "npm run build && node --enable-source-maps --test 'dist/**/*.spec.js'",
+    "test:coverage": "npm run build && node --enable-source-maps --test --experimental-test-coverage 'dist/**/*.spec.js'",
+    "test:integration": "npm run test:docker:up && npm test && npm run test:docker:down",
+    "test:docker:up": "docker-compose up -d && npm run test:wait",
+    "test:docker:down": "docker-compose down -v",
+    "test:wait": "tsx scripts/wait-for-services.ts",
+    "dev:services": "docker-compose up -d",
+    "dev:services:down": "docker-compose down -v",
+    "extract-examples": "tsx scripts/extract-typedoc-examples.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "version:patch": "npm version patch -m 'chore: bump version to %s'",
+    "version:minor": "npm version minor -m 'chore: bump version to %s'",
+    "version:major": "npm version major -m 'chore: bump version to %s'",
+    "version:prepatch": "npm version prepatch --preid=beta -m 'chore: bump version to %s'",
+    "version:preminor": "npm version preminor --preid=beta -m 'chore: bump version to %s'",
+    "version:premajor": "npm version premajor --preid=beta -m 'chore: bump version to %s'",
+    "version:prerelease": "npm version prerelease --preid=beta -m 'chore: bump version to %s'",
+    "version:patch:dry": "npm version patch --no-git-tag-version",
+    "version:minor:dry": "npm version minor --no-git-tag-version",
+    "version:major:dry": "npm version major --no-git-tag-version",
+    "version:prepatch:dry": "npm version prepatch --preid=beta --no-git-tag-version",
+    "version:preminor:dry": "npm version preminor --preid=beta --no-git-tag-version",
+    "version:premajor:dry": "npm version premajor --preid=beta --no-git-tag-version",
+    "version:prerelease:dry": "npm version prerelease --preid=beta --no-git-tag-version",
+    "release:patch": "npm run version:patch && git push && git push --tags",
+    "release:minor": "npm run version:minor && git push && git push --tags",
+    "release:major": "npm run version:major && git push && git push --tags",
+    "release:prepatch": "npm run version:prepatch && git push && git push --tags",
+    "release:preminor": "npm run version:preminor && git push && git push --tags",
+    "release:premajor": "npm run version:premajor && git push && git push --tags",
+    "release:prerelease": "npm run version:prerelease && git push && git push --tags"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elaraai/east-node.git",
+    "directory": "packages/east-node-io"
+  },
+  "keywords": [
+    "east",
+    "elara",
+    "node",
+    "io",
+    "database",
+    "sql",
+    "nosql",
+    "s3",
+    "ftp",
+    "sftp",
+    "platform"
+  ],
+  "author": "Elara AI Pty Ltd",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "@elaraai/east-node-std": "*",
+    "@types/adm-zip": "^0.5.7",
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.18.1",
+    "@types/pg": "^8.11.10",
+    "@types/ssh2-sftp-client": "^9.0.5",
+    "@types/tar-stream": "^3.1.4",
+    "@typescript-eslint/eslint-plugin": "^8.42.0",
+    "@typescript-eslint/parser": "^8.42.0",
+    "eslint": "^9.34.0",
+    "eslint-plugin-headers": "^1.3.3",
+    "tsx": "^4.19.2",
+    "typescript": "~5.9.2"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.713.0",
+    "@aws-sdk/s3-request-presigner": "^3.713.0",
+    "@elaraai/east": "^0.0.1-beta.0",
+    "adm-zip": "^0.5.16",
+    "basic-ftp": "^5.0.5",
+    "better-sqlite3": "^11.0.0",
+    "ioredis": "^5.4.2",
+    "mongodb": "^6.11.0",
+    "mysql2": "^3.11.5",
+    "pg": "^8.13.1",
+    "ssh2-sftp-client": "^11.0.0",
+    "tar-stream": "^3.1.7",
+    "xlsx": "^0.18.5"
+  }
+}