Cement

An agnostic platform abstraction layer for TypeScript/JavaScript and Go that provides consistent APIs across Node.js, Deno, Cloudflare Workers, and other runtimes.

Overview

Cement provides a unified interface for common system operations, logging, and utilities across different JavaScript/TypeScript runtimes and Go. Write your code once and run it anywhere - whether that's Node.js, Deno, browsers, or Cloudflare Workers.

Key Features

$3

Cross-platform system operations through a unified interface:

``typescript
interface SysAbstraction {
Time(): Time;
Stdout(): WritableStream;
Stderr(): WritableStream;
NextId(): string;
Random0ToValue(value: number): number;
System(): SystemService;
FileSystem(): FileService;
}
`

$3

Inspired by Go's zerolog, providing efficient structured logging:

`typescript
logger
.Str("user", "john")
.Uint64("id", 123)
.Info()
.Log("User logged in");
`

$3

- Result & Option Types: Type-safe error handling inspired by Rust
- Future: Promise-based async utilities
- URI Handling: Mutable URL utilities for safe URL manipulation
- Crypto: Platform-agnostic cryptographic operations
- Tracer: Distributed tracing support
- LRU Cache: Efficient least-recently-used cache implementation
- Path Operations: Cross-platform path manipulation
- HTTP Headers: Type-safe HTTP header utilities
- Poller: Polling utilities with configurable intervals
- Timeouted: Timeout wrapper for async operations

Installation

$3

`bash
npm install @adviser/cement
`

$3

`bash
pnpm add @adviser/cement
`

$3

`typescript
import { ... } from "jsr:@adviser/cement";
`

$3

`bash
go get github.com/mabels/cement
`

Usage

$3

`typescript
import { BuildBasicSystemService } from "@adviser/cement/node";

const sys = BuildBasicSystemService();
const logger = sys.Logger();

logger
.Str("module", "app")
.Info()
.Log("Application started");

// Use file system operations
const fs = sys.FileSystem();
await fs.writeFile("output.txt", "Hello World");
`

$3

`typescript
// Node.js
import { BuildBasicSystemService } from "@adviser/cement/node";

// Deno
import { BuildBasicSystemService } from "@adviser/cement/deno";

// Cloudflare Workers
import { BuildBasicSystemService } from "@adviser/cement/cf";

// Browser/Web
import { BuildBasicSystemService } from "@adviser/cement/web";
`

$3

`typescript
import { Result } from "@adviser/cement";

function divide(a: number, b: number): Result {
if (b === 0) {
return Result.Err(new Error("Division by zero"));
}
return Result.Ok(a / b);
}

const result = divide(10, 2);
if (result.isOk()) {
console.log("Result:", result.unwrap());
} else {
console.error("Error:", result.unwrapErr());
}
`

Documentation

For comprehensive documentation, API references, and advanced usage examples, visit:

https://mabels.github.io/cement

Supported Platforms

- Node.js (>= 20.19.0)
- Deno
- Cloudflare Workers
- Web Browsers
- Go (>= 1.22.0)

Development

`bash


Install dependencies

pnpm install

Run tests

pnpm test

Run tests for specific platform

pnpm test:js # Node.js/JavaScript tests
pnpm test:deno # Deno tests

Build

pnpm build

Lint

pnpm lint

Format code

pnpm format
``

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache License 2.0 - See LICENSE for details.

Repository

- GitHub: https://github.com/mabels/cement
- Issues: https://github.com/mabels/cement/issues
- npm: @adviser/cement
- JSR: @adviser/cement