🪐 Orbit-Storage

Orbit-Storage is a powerful, production-ready storage abstraction designed specifically for the TitanPL Gravity Runtime.

It allows developers to write storage logic once and switch seamlessly between Local Filesystem and Cloud Storage (S3, Cloudflare R2) without changing application code.

Built to be lightweight, Orbit-Storage relies on Titan's native drift() boundary engine via orbit-http and @titanpl/native APIs, ensuring zero Node.js dependencies and maximum performance.

🔥 Features

• Unified API: Identical methods across all drivers (put, get, delete, exists).
• Titan-Native: Synchronous execution model compatible with Titan's architecture.
• Security-First: Built-in protection against Path Traversal Attacks in the local driver.
• Cloud-Ready: Native support for S3 and Cloudflare R2 using secure Presigned URLs.
• Zero Configuration Overload: No complex authentication setup; it just works.
• Enterprise JSDoc: Full TypeScript support with detailed IntelliSense.

⚡ Installation

Install into your Titan project via npm:

npm install orbit-storage

🏗️ Usage

1. Local Filesystem Driver

The local driver is perfect for development or simple persistent storage. It resolves all paths safely relative to your project root.

import storage from "orbit-storage";

const disk = storage.create({
  driver: "local",
  dir: "storage/uploads" // Automatically created if it doesn't exist
});

// Storing a file
disk.put("users/profile_1.json", JSON.stringify({ name: "Titan Programmer" }));

// Checking if it exists
if (disk.exists("users/profile_1.json")) {
    const data = disk.get("users/profile_1.json");
    console.log(data);
}

2. Cloud Storage (S3 & Cloudflare R2)

Orbit-Storage uses Presigned URLs to stay lightweight. This approach is highly secure as it avoids storing long-term credentials in your runtime and leverages temporary access tokens.

import storage from "orbit-storage";

const cloud = storage.create({
  driver: "s3" // or "r2"
});

// Uploading to a presigned URL
cloud.put(presignedPutUrl, fileData);

// Downloading from a presigned URL
const fileContent = cloud.get(presignedGetUrl);

🛡️ Path Traversal Protection

The local driver includes strict validation. Attempts to use paths like ../../etc/passwd or ../my-titan-app/.env will be proactively blocked by Orbit-Storage to keep your server safe.

📚 API Reference

storage.create(config)

Initializes the driver.

• driver: "local" | "s3" | "r2"
• dir: (Local only) The storage directory.

instance.put(path, data)

Persists data to the storage provider.

• Returns { path: string }.

instance.get(path)

Retrieves data from the storage provider.

• Returns the content as a string.
• Throws Error if file not found.

instance.delete(path)

Removes the file from storage.

instance.exists(path)

Returns boolean.

🤝 Community & Support

Orbit-Storage is a community package for the TitanPL ecosystem. It follows the principles of the Orbit Ecosystem:

1. Minimal code surface (< 400 lines).
2. Predictable, synchronous APIs.
3. Native performance without Node shims where possible.

📄 License

MIT License. Created for the Titan Planet community.