Release

@lossless.zone/objectstorage is a self-hosted, S3-compatible object storage server packaged as a single Docker image. It gives you an S3 endpoint for applications, a browser-based management UI for humans, and a Rust-powered storage engine underneath.

The short version: it is the storage box you can run yourself when you want S3 semantics without signing up for a cloud bucket, wiring together MinIO, or building an admin console from scratch.

Why Another Object Storage Server?

Object storage is one of those pieces of infrastructure that looks simple until you operate it. The protocol is familiar: buckets, keys, objects, credentials, policies, multipart uploads. The hard part is everything around it.

You need a process that starts predictably in Docker. You need credentials that can be managed without rebuilding an image. You need a UI for buckets, policies, object browsing, and quick inspection. You need an S3-compatible API so existing SDKs and tools keep working. If the storage grows beyond one disk, you need clustering, erasure coding, drive awareness, and repair behavior that does not require a separate product.

@lossless.zone/objectstorage wraps those requirements into one product layer. The storage protocol and data path are handled by @push.rocks/smartstorage, a Rust-backed S3-compatible engine. The objectstorage package adds the Docker runtime, Deno-based control process, admin authentication, management APIs, and a dees-catalog web UI.

┌───────────────────────────────────────────────────────────────┐
│                      objectstorage                            │
│                                                               │
│  Management UI                 Storage Engine                 │
│  port 3000                     port 9000                      │
│                                                               │
│  dees-catalog SPA              smartstorage                   │
│  typed ops API      ───────▶   Rust S3 server                 │
│  admin auth                    SigV4, policies, streaming I/O │
│                                                               │
│  optional cluster layer: QUIC, erasure coding, drive paths    │
└───────────────────────────────────────────────────────────────┘

Ecosystem note. lossless.zone is the storage-facing product line in the foss.global stack. objectstorage is the runnable service layer; @push.rocks/smartstorage is the lower-level S3 engine underneath it.

A Docker Container, Not a Framework Exercise

The recommended start path is intentionally boring:

docker run -d \
  --name objectstorage \
  -p 9000:9000 \
  -p 3000:3000 \
  -v objstdata:/data \
  -e OBJST_ACCESS_KEY=myadminkey \
  -e OBJST_SECRET_KEY=mysupersecret \
  -e OBJST_ADMIN_PASSWORD=myuipassword \
  code.foss.global/lossless.zone/objectstorage:latest

Port 9000 is the S3-compatible API. Port 3000 is the management UI. /data is the persistent volume for bucket data and product metadata.

The image is Alpine-based, runs Deno in production, uses tini for signal handling, and exposes the cluster transport port 4433 for distributed deployments. The build is multi-stage: a Node/pnpm stage bundles the frontend with @git.zone/tsbundle, and the final image contains the Deno runtime, backend code, shared interfaces, and bundled web assets.

That split matters. This is not just a library that happens to start a server. It is meant to be deployed as a service.

S3 Compatibility Where Applications Need It

Applications talk to objectstorage through the normal S3 model. Any S3-compatible client can point at http://localhost:9000, use path-style addressing, and authenticate with the configured access key and secret.

import { S3Client, PutObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';

const s3 = new S3Client({
  endpoint: 'http://localhost:9000',
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'admin',
    secretAccessKey: 'admin',
  },
  forcePathStyle: true,
});

await s3.send(new PutObjectCommand({
  Bucket: 'my-bucket',
  Key: 'hello.txt',
  Body: 'Hello, object storage!',
}));

const result = await s3.send(new ListObjectsV2Command({
  Bucket: 'my-bucket',
}));

console.log(result.Contents);

The underlying smartstorage engine handles the protocol details: AWS SigV4 authentication, IAM-style bucket policies, multipart uploads, byte-range requests, and streaming I/O. For large files, that distinction is important. The engine is Rust-based and designed around streaming and backpressure rather than loading whole objects into a JavaScript process.

The Management UI Is Part of the Product

Raw S3 compatibility is useful for applications. It is not enough for operators.

The management UI is served from the same container on port 3000. After logging in as admin with OBJST_ADMIN_PASSWORD, you get views for server status, buckets, objects, policies, access keys, and configuration.

The object browser is the part users notice first. It behaves more like a file manager than a cloud API explorer: column-style browsing, folder prefixes, upload, download, preview, move, rename, delete, and context menus. Text objects can be opened in a Monaco-powered code editor and saved back to storage. PDFs render inline with page navigation, zoom, thumbnails, print, and download controls.

That is a practical difference from a minimal S3 server. Operators do not need to keep switching between aws s3 ls, a bucket policy JSON file, and a separate dashboard. The common workflows are in the product.

Named Policies Instead of Copy-Pasted JSON

S3 bucket policies are powerful, but raw policy JSON is awkward to manage by hand. objectstorage adds a named policy layer on top.

You create a reusable policy once, then attach it to one or more buckets. The PolicyManager persists named policies under the storage directory, tracks bucket attachments, merges attached statements, replaces the ${bucket} placeholder with the concrete bucket name, and applies the resulting S3 policy to the bucket.

[
  {
    "Sid": "PublicRead",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::${bucket}/*"
  }
]

Attach that policy to assets, downloads, and public-site, and each bucket receives the correct concrete resource ARN. Updating the named policy recomputes the attached bucket policies. Deleting a policy detaches it and reapplies the affected buckets.

This is a small abstraction, but it removes one of the most common sources of S3 admin drift: nearly identical policy documents copied across buckets and edited manually.

Runtime Credentials and Admin State

objectstorage has two authentication surfaces.

The S3 API uses access-key credentials and SigV4 verification. The admin UI uses a JWT-backed login flow with the fixed username admin and the configured admin password.

The default standalone configuration is deliberately simple:

OBJST_ACCESS_KEY=admin
OBJST_SECRET_KEY=admin
OBJST_ADMIN_PASSWORD=admin
OBJST_REGION=us-east-1

Production deployments should override those values. Credentials can also be managed from the UI. The container persists runtime-managed access credentials in /data/.objectstorage/admin-config.json, so credential changes survive restart when /data is backed by a persistent volume.

The product boundary here is clear: objectstorage owns admin UX, product metadata, and startup configuration. smartstorage owns the S3 auth and policy enforcement path.

@push.rocks/smartproxy is a production proxy that handles TCP, TLS, HTTP reverse proxying, WebSockets, UDP, QUIC/HTTP3, load balancing, and kernel-level NFTables forwarding — all from a single route-based TypeScript API. Under the hood, a Rust binary does every byte of networking. Your TypeScript code just describes what should happen. The Rust engine figures out how — fast.

The Problem with Proxy Configuration

If you've ever set up nginx, HAProxy, or Envoy, you know the drill: write YAML or a bespoke config language, restart the process, hope the syntax is right, grep through docs for the directive name you forgot. There's no type checking, no autocomplete, no way to express "route this domain to backend A unless the path starts with /api, in which case terminate TLS and forward to backend B with rate limiting."

SmartProxy replaces all of that with typed TypeScript objects. A route is a match/action pair. The match says what traffic to capture. The action says what to do with it. TypeScript catches your mistakes before the proxy even starts.

30 Seconds to HTTPS

import { SmartProxy } from '@push.rocks/smartproxy';

const proxy = new SmartProxy({
  acme: {
    email: 'ssl@yourdomain.com',
    useProduction: true
  },
  routes: [
    // Redirect HTTP → HTTPS
    {
      name: 'redirect-to-https',
      match: { ports: 80, domains: 'app.example.com' },
      action: {
        type: 'socket-handler',
        socketHandler: SocketHandlers.httpRedirect('https://{domain}{path}', 301)
      }
    },
    // Terminate TLS, forward to backend
    {
      name: 'app-https',
      match: { ports: 443, domains: 'app.example.com' },
      action: {
        type: 'forward',
        targets: [{ host: 'localhost', port: 3000 }],
        tls: { mode: 'terminate', certificate: 'auto' }
      }
    }
  ]
});

await proxy.start();

Two routes. The first catches HTTP on port 80 and redirects to HTTPS using a built-in socket handler with template variables ({domain}, {path}). The second terminates TLS on port 443 with an automatic Let's Encrypt certificate and forwards plain HTTP to your backend. No certificate files to manage. No cron jobs for renewal. The Rust engine handles ACME challenges, stores nothing to disk, and calls back into your TypeScript code if you want custom persistence.

The Route Model

Every route in SmartProxy follows the same shape:

{
  name: 'api-route',
  match: {
    ports: 443,
    domains: 'api.example.com',
    path: '/v1/*'
  },
  action: {
    type: 'forward',
    targets: [{ host: 'backend', port: 8080 }],
    tls: { mode: 'terminate', certificate: 'auto' }
  }
}

The match block supports ports (single, array, or ranges), domains (exact or wildcard), paths, transport protocol (tcp, udp, or all), application-layer protocol (http, tcp, quic), client IP ranges, TLS versions, and HTTP headers. The action block is either forward (proxy to backends) or socket-handler (hand the raw socket to your TypeScript function). Every field is typed. The match criteria compose — you can have a route that only fires for QUIC traffic from a specific IP range on a specific port with a specific SNI hostname.

Routes are evaluated in priority order. First match wins. You can update them at runtime with proxy.updateRoutes() — the operation is atomic and mutex-locked, so in-flight connections aren't affected.

Three TLS Modes

SmartProxy supports three ways to handle TLS, and the choice matters:

Passthrough routes encrypted traffic based on the SNI hostname without decrypting it. The backend handles TLS. The proxy never sees plaintext. This is what you want when you can't or don't want to terminate TLS at the proxy layer.

{
  name: 'tls-passthrough',
  match: { ports: 443, domains: 'secure.example.com' },
  action: {
    type: 'forward',
    targets: [{ host: 'backend-that-handles-tls', port: 8443 }],
    tls: { mode: 'passthrough' }
  }
}

Terminate decrypts at the proxy and forwards plain HTTP to the backend. This is the standard reverse proxy model. The proxy can inspect HTTP headers, match paths, add headers, and do request-level routing.

Terminate-and-reencrypt decrypts at the proxy, then re-encrypts to the backend. HTTP traffic gets full per-request routing (Host header, path matching) via the HTTP proxy; non-HTTP traffic uses a raw TLS-to-TLS tunnel. This is for zero-trust environments where traffic must be encrypted on every hop.

The Rust Engine

All networking — TCP listeners, TLS handshakes, HTTP parsing, connection pooling, security enforcement, metrics collection, UDP sockets, QUIC — runs inside a Rust binary. The TypeScript process communicates with it over JSON IPC on stdin/stdout. This isn't an FFI binding or a WASM module. It's a separate process.

The architecture diagram tells the story:

┌─────────────────────────────────────────────────┐
│              Your Application                    │
│     (TypeScript — routes, config, handlers)      │
└──────────────────┬──────────────────────────────┘
                   │  IPC (JSON over stdin/stdout)
┌──────────────────▼──────────────────────────────┐
│              Rust Proxy Engine                    │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │ TCP/TLS │ │  HTTP    │ │  Route  │           │
│  │ Listener│ │  Proxy   │ │ Matcher │           │
│  └─────────┘ └─────────┘ └─────────┘           │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │   UDP   │ │Security │ │ Metrics │           │
│  │  QUIC   │ │ Enforce │ │ Collect │           │
│  └─────────┘ └─────────┘ └─────────┘           │
└─────────────────────────────────────────────────┘

The process split is deliberate. The Rust engine doesn't parse config files. The TypeScript side never touches a raw packet. When a route uses a JavaScript socket handler or a dynamic host function (a callback that can't be serialized to Rust), the Rust engine relays that connection back to a TypeScript-side Unix socket server. Everything else stays in Rust.

Ecosystem note. The TypeScript/Rust bridge pattern keeps configuration and API ergonomics in TypeScript while the Rust subprocess owns the packet path. smartproxy is one of the clearest examples because route objects stay typed and byte handling stays native.

Load Balancing with Health Checks

{
  name: 'load-balanced-app',
  match: { ports: 443, domains: 'app.example.com' },
  action: {
    type: 'forward',
    targets: [
      { host: 'server1.internal', port: 8080 },
      { host: 'server2.internal', port: 8080 },
      { host: 'server3.internal', port: 8080 }
    ],
    tls: { mode: 'terminate', certificate: 'auto' },
    loadBalancing: {
      algorithm: 'round-robin',
      healthCheck: {
        path: '/health',
        interval: 30000,
        timeout: 5000,
        unhealthyThreshold: 3,
        healthyThreshold: 2
      }
    }
  }
}

Three algorithms: round-robin, least-connections, and ip-hash. Health checks run at the configured interval and remove backends that fail the unhealthy threshold. They come back when they pass the healthy threshold. No external health checker needed.

UDP, QUIC, and HTTP/3

SmartProxy isn't TCP-only. Set transport: 'udp' in a route match and you're listening for datagrams. Pair it with a datagramHandler and you can implement any UDP protocol in TypeScript:

const udpHandler: TDatagramHandler = (datagram, info, reply) => {
  console.log(`UDP from ${info.sourceIp}:${info.sourcePort}`);
  reply(datagram); // Echo it back
};

const proxy = new SmartProxy({
  routes: [{
    name: 'udp-echo',
    match: { ports: 5353, transport: 'udp' },
    action: {
      type: 'socket-handler',
      datagramHandler: udpHandler,
      udp: {
        sessionTimeout: 60000,
        maxSessionsPerIP: 100,
        maxDatagramSize: 65535
      }
    }
  }]
});

For QUIC and HTTP/3, set protocol: 'quic' and configure TLS (QUIC requires TLS 1.3). SmartProxy can receive QUIC on the frontend and translate to TCP

@push.rocks/smartvpn tunnels all VPN traffic inside a standard WebSocket connection over HTTPS. To any firewall, DPI box, or network observer, it looks indistinguishable from ordinary web traffic (the same kind of connection a chat app or real-time dashboard would open on port 443). It passes through Cloudflare, corporate proxies, and restrictive networks that block traditional VPN protocols on sight. Under the hood, smartvpn splits the work between a TypeScript control plane for configuration, client management, and telemetry, and a Rust data plane that handles encryption, tunneling, QoS, and packet classification at native speed. The two halves talk over typed JSON-lines IPC. Neither side compromises.

The Architecture in 30 Seconds

Your TypeScript code instantiates a VpnClient or VpnServer. Under the hood, smartvpn uses @push.rocks/smartrust to spawn a Rust binary (smartvpn_daemon) and opens a bidirectional JSON channel to it, either over stdio for development or a Unix socket for production. Every method call on the TypeScript side becomes a JSON command to the Rust daemon. Every response is typed end to end.

The Rust daemon handles everything that needs to be fast: Noise NK handshakes, XChaCha20-Poly1305 encryption with random 24-byte nonces, TUN device I/O, a three-tier priority queue (ICMP/DNS/SSH at the top, bulk flows at the bottom), per-client token-bucket rate limiting, adaptive keepalives, and automatic path MTU calculation. The TypeScript side never touches a raw packet. The Rust side never parses a config file.

Ecosystem note. @push.rocks/smartrust is the runtime side of the TypeScript/Rust bridge. smartvpn uses it so callers work with VpnClient and VpnServer while a Rust daemon handles privileged packet and crypto work.

What the TypeScript Looks Like

Connecting as a client is about what you would expect from a well-designed Node library:

import { VpnClient } from '@push.rocks/smartvpn';

const client = new VpnClient({
  transport: { transport: 'stdio' },
});
await client.start();

const { assignedIp } = await client.connect({
  serverUrl: 'wss://vpn.example.com/tunnel',
  serverPublicKey: 'BASE64_SERVER_PUBLIC_KEY',
  dns: ['1.1.1.1', '8.8.8.8'],
  mtu: 1420,
});
console.log(`Connected: ${assignedIp}`);

That's it. Behind that await, the TypeScript layer spawned a Rust daemon, negotiated a Noise NK handshake with the server, stood up a TUN interface, and started routing encrypted traffic through a WebSocket tunnel. The transport choice (WebSocket over HTTPS) is deliberate. It passes through Cloudflare, corporate proxies, and anything else that terminates TLS. Most WireGuard setups choke in these environments. smartvpn doesn't.

Once connected, you get real-time telemetry for free. Call client.getConnectionQuality() and you get back smoothed RTT, jitter, loss ratio, and a link health classification (healthy / degraded / critical) — all measured by the daemon's own adaptive keepalive system, not by WebSocket pings that Cloudflare would swallow.

Easy Serverside Control over Clients

The server API (via VpnServer class) gives you a typed control surface over every connected client, and you can change anything at runtime without dropping connections.

You can list clients, pull per-client telemetry (bytes in/out, packets dropped, keepalive history), set individual rate limits with server.setClientRateLimit(), and kick anyone with server.disconnectClient(). Rate limits use a token-bucket algorithm at byte granularity in the Rust daemon. When you call setClientRateLimit('client-id', 5_000_000, 10_000_000), the bucket parameters change in the Rust process instantly — no reconnection, no config reload, no restart. Most VPN stacks need custom C extensions for this kind of runtime control.

KeepAlive and Adaptive HealthChecks

If you tunnel over WebSocket through a reverse proxy like Cloudflare, your WebSocket-level pings get swallowed. The proxy responds on behalf of the server, so your client thinks the link is healthy when the backend might be dead. smartvpn solves this with application-level keepalives — custom ping/pong frames inside the encrypted tunnel carrying 8-byte timestamps for precise RTT measurement.

The interval adapts. The daemon runs a three-state finite state machine: healthy (60s interval), degraded (30s), and critical (10s). Transitions have hysteresis — you need three consecutive good checks to upgrade from degraded to healthy, two bad ones to downgrade, which prevents the flapping that wastes bandwidth on unstable mobile connections. Dead peer detection fires after three consecutive timeouts in critical state. The whole thing runs inside the Rust process with zero allocations in steady state.

Quality of Service

The Rust data plane classifies every decrypted IP packet into three priority tiers by inspecting headers — no deep packet inspection, just port numbers and packet size. ICMP, DNS (port 53), SSH (port 22), and small packets under 128 bytes get high priority. Bulk flows that exceed 1 MB within a 60-second window get demoted to low. Everything else is normal. The priority channels drain with biased scheduling: high-priority packets always go first.

Under backpressure, the drop policy is equally deliberate: low-priority packets get dropped silently, normal packets get dropped next, and high-priority packets wait up to 5ms before being dropped as a last resort. Drop statistics are tracked per priority level and exposed through the telemetry API. This means your SSH session stays snappy even when someone on the same VPN is saturating the link with a large download.

Crypto Choices

The Noise NK handshake pattern means the client knows the server's static public key upfront but doesn't authenticate itself — the same trust model as connecting to a website via TLS. Two DH operations (ephemeral-static, then ephemeral-ephemeral) produce forward-secret transport keys. Post-handshake, everything goes through XChaCha20-Poly1305 with random 24-byte nonces. The large nonce space means you never need counter synchronization between peers; just generate a random nonce per packet. The wire format is minimal: [nonce:24B][ciphertext][tag:16B], inside a binary frame of [type:1B][length:4B][payload].

The MTU Math

The daemon also calculates tunnel overhead precisely. IP header (20 bytes) + TCP with timestamps (32 bytes) + WebSocket framing (6 bytes) + VPN frame header (5 bytes) + Noise AEAD tag (16 bytes) = 79 bytes of overhead. On a standard 1500-byte Ethernet link, that gives you an effective TUN MTU of 1421 bytes. The default of 1420 is conservative and correct. Oversized packets get an ICMP Fragmentation Needed written

In the world of TypeScript development, finding the right database tools that combine type safety with powerful features can be challenging. As applications grow in complexity, particularly in distributed environments, the need for robust data management becomes ever more critical. This is where @push.rocks/smartdata enters the picture - a TypeScript-first MongoDB wrapper designed to simplify complex data operations while providing powerful features for modern application development.

What is @push.rocks/smartdata?

@push.rocks/smartdata is a comprehensive MongoDB wrapper that provides strong TypeScript integration, offering type-safe operations, automated schema handling, and advanced features for distributed systems. Created by the foss.global team (which I am a part of), this library aims to simplify database interactions while adding powerful features that extend MongoDB's capabilities.

Ecosystem note. push.rocks is the shared library namespace in the foss.global stack. smartdata is a MongoDB-backed data layer for TypeScript services, not a hosted database product.

Key Features That Set It Apart

What makes @push.rocks/smartdata stand out from other MongoDB wrappers? Let's explore its most distinctive features:

1. True TypeScript-First Approach

Unlike many libraries that add TypeScript as an afterthought, @push.rocks/smartdata is built from the ground up with TypeScript in mind. This provides several advantages:

• Decorator-Based Schema Definition: Define your MongoDB schemas using TypeScript decorators
• Type-Safe CRUD Operations: Eliminate runtime errors with compile-time type checking
• Deep Query Type Safety: Fully type-safe queries for nested object properties via DeepQuery<T>

2. Advanced Search Capabilities

The library implements a powerful and intuitive search system that goes beyond basic queries:

// Define a model with searchable fields
@Collection(() => db)
class Product extends SmartDataDbDoc<Product, Product> {
  @unI() public id: string = 'product-id';
  @svDb() @searchable() public name: string;
  @svDb() @searchable() public description: string;
  @svDb() @searchable() public category: string;
  @svDb() public price: number;
}

// Advanced search options
await Product.search('"Kindle Paperwhite"'); // Exact phrase across all fields
await Product.search('Air*'); // Wildcard search
await Product.search('name:Air*'); // Field-scoped wildcard
await Product.search('category:Electronics AND name:iPhone'); // Boolean operators
await Product.search('(Furniture OR Electronics) AND Chair'); // Grouping

This search functionality supports Lucene-style queries with exact matches, wildcards, field-scoping, boolean operators, and more - all while maintaining type safety.

3. EasyStore for Simple Key-Value Storage

For simpler data needs, @push.rocks/smartdata offers EasyStore - a type-safe key-value storage system with automatic persistence:

interface ConfigStore {
  apiKey: string;
  settings: {
    theme: string;
    notifications: boolean;
  };
}

// Create a type-safe EasyStore
const store = await db.createEasyStore<ConfigStore>('app-config');

// Write and read with full type safety
await store.writeKey('apiKey', 'secret-api-key-123');
await store.writeKey('settings', { theme: 'dark', notifications: true });

const apiKey = await store.readKey('apiKey'); // Type: string
const settings = await store.readKey('settings'); // Type: { theme: string, notifications: boolean }

4. Built-in Distributed Coordination

One of the most powerful features is the built-in support for distributed systems:

// Create a distributed coordinator
const coordinator = new SmartdataDistributedCoordinator(db);

// Start coordination
await coordinator.start();

// Handle leadership changes
coordinator.on('leadershipChange', (isLeader) => {
  if (isLeader) {
    // This instance is now the leader
    startPeriodicJobs();
  } else {
    // This instance is no longer the leader
    stopPeriodicJobs();
  }
});

// Execute tasks only on the leader
await coordinator.executeIfLeader(async () => {
  // This code only runs on the leader instance
  await runImportantTask();
});

This makes it significantly easier to build reliable distributed applications with leader election, task coordination, and more.

5. Real-Time Data Synchronization

For applications requiring real-time updates, @push.rocks/smartdata provides watchers with RxJS integration:

// Create a watcher for active users
const watcher = await User.watch(
  { active: true },
  { fullDocument: true, bufferTimeMs: 100 }
);

// Subscribe to changes using RxJS
watcher.changeSubject.subscribe((change) => {
  console.log('Change operation:', change.operationType); 
  console.log('Document changed:', change.docInstance);
  
  // Handle different operations
  if (change.operationType === 'insert') {
    notifyNewUser(change.docInstance);
  }
});

This simplifies building reactive applications that respond to data changes in real-time.

Practical Implementation

Let's walk through a practical implementation to see how @push.rocks/smartdata can be used in a real-world scenario.

Setting Up Your Database Connection

First, establish a connection to your MongoDB database:

import { SmartdataDb } from '@push.rocks/smartdata';

// Create a database instance
const db = new SmartdataDb({
  mongoDbUrl: 'mongodb://localhost:27017/myapp',
  mongoDbName: 'myapp',
  mongoDbUser: 'username',
  mongoDbPass: 'password',
});

// Initialize and connect
await db.init();

Defining Your Data Models

Next, define your data models using TypeScript classes with decorators:

import {
  SmartDataDbDoc,
  Collection,
  unI,
  svDb,
  index,
  searchable,
} from '@push.rocks/smartdata';
import { ObjectId } from 'mongodb';

@Collection(() => db)
class User extends SmartDataDbDoc<User, User> {
  @unI()
  public id: string = 'user-' + Math.random().toString(36).substring(2, 9);

  @svDb()
  @searchable()
  public username: string;

  @svDb()
  @searchable()
  @index()
  public email: string;

  @svDb()
  public organizationId: ObjectId; // Stored as BSON ObjectId

  @svDb()
  public profilePicture: Buffer; // Stored as BSON Binary

  @svDb({
    serialize: (data) => JSON.stringify(data),
    deserialize: (data) => JSON.parse(data),
  })
  public preferences: Record<string, any>;

  constructor(username: string, email: string) {
    super();
    this.username = username;
    this.email = email;
  }
}

Performing CRUD Operations

With your models defined, you can now perform fully type-safe CRUD operations:

// Create a user
const user = new User('johndoe', 'john@example.com');
user.preferences = { theme: 'dark', notifications: true };
await user.save();

// Retrieve users
const singleUser = await User.getInstance({ username: 'johndoe' });
const users = await User.getInstances({ email: /example\.com$/ });

// Update a user
singleUser.email = 'john.doe@example.com';
await singleUser.save();

// Upsert operation
const upsertedUser = await User.upsert(
  { username: 'janedoe' },
  { email: 'jane@example.com', preferences: { theme: 'light' } }
);

// Delete a user
await singleUser.delete();

Using Advanced Features

For more complex scenarios, leverage the advanced features:

// Using transactions for atomic operations
const session = db.startSession();
try {
  await session.withTransaction(async () => {
    const sender = await User.getInstance({ id: 'user1' }, session);
    const recipient = await User.getInstance({ id: 'user2' }, session);
    
    // Transfer credits atomically
    sender.credits -= 100;
    recipient.credits += 100;
    
    await sender.save({ session });
    await recipient.save({ session });
  });
} finally {
  await session.endSession();
}

// Implementing document lifecycle hooks
@Collection(() => db)
class Order extends SmartDataDbDoc<Order, Order> {
  @unI()
  public id: string = 'order-' + Date.now();

  @svDb()
  public items: string[];

  @svDb()
  public total: number = 0;

  // Hook called before saving
  async beforeSave() {
    // Calculate total from