Skip to main content

Database abstraction layer for ClashOn gaming platform.

This package works with Node.js, Deno, BrowsersIt is unknown whether this package works with Cloudflare Workers, Bun
It is unknown whether this package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
It is unknown whether this package works with Bun
This package works with Browsers
JSR Score
70%
Published
6 days ago (0.2.6)

Platform Persistence Library

A platform-agnostic library for interacting with the platform's persistence layer (Supabase).

Overview

This library provides a unified interface for:

  • Database operations (CRUD)
  • Realtime subscriptions
  • Authentication management
  • Player balances and transactions

Usage Pattern

1. Initialization

Initialize the client once at your application's entry point:

import { DB } from '@clashon/platform-persistence'

// Initialize with base configuration
DB.init({
    supabaseUrl: 'your-supabase-url',
    supabaseKey: 'your-anon-key', // or service role key for backend services
})

2. Authentication

Update realtime auth token whenever new custom claims are received:

// After receiving new JWT with custom claims
DB.realtimeAuth(customClaimsJwt)

This pattern is particularly useful when:

  • Player logs in and receives initial JWT
  • Player joins a game and receives game-specific JWT
  • JWT is refreshed with new claims

3. Subscriptions

Set up subscriptions with proper error handling:

const channel = DB.subscribeToMasterRounds(
    userId,
    (payload) => {
        // Handle new master round
        console.log('New master round:', payload)
    },
    (status, err) => {
        // Handle subscription status changes
        console.log('Subscription status:', status, err)
    },
)

4. Cleanup

Always clean up resources when done:

// Unsubscribe from specific channel
channel.unsubscribe()

// Disconnect client entirely
DB.disconnect()

Matchmaking Flow

The following sequence diagram illustrates the matchmaking process and how the persistence library is used:

sequenceDiagram
    participant Player as Player (TMA)
    participant Backend as Platform Backend
    participant Supabase as Supabase DB
    participant Matchmaking as Matchmaking Service


    Matchmaking->>Supabase: SUBSCRIBE to MatchmakingRequest

    Note over Player: Subscribe to MasterRound updates first
    Player->>Supabase: SUBSCRIBE to MasterRound

    Note over Player: Send matchmaking request
    Player->>Backend: POST /matchmaking
    Backend->>Supabase: INSERT MatchmakingRequest
    Supabase-->>Backend: mr_id
    Backend-->>Player: mr_id
    Supabase-->>Matchmaking: mr


    Note over Matchmaking: Process requests every 30s
    Matchmaking->>Supabase: INSERT MasterRound (grouped players)


    alt MasterRound assigned
        Supabase-->>Player: MasterRound via subscription
    else Timeout (31s)
        Note over Player: Query assigned round on timeout
        Player->>Supabase: SELECT MasterRound WHERE id = mr_id
        Supabase-->>Player: Return assigned MasterRound
    end

    Note over Player: Continue with game setup

Key Features

  1. Platform Agnostic

    • Works in any JavaScript runtime (Deno, Node.js, browsers)
    • No runtime-specific dependencies
  2. Type Safety

    • Full TypeScript support
    • Database schema types included
  3. Realtime Support

    • Subscription management
    • Automatic reconnection
    • Status monitoring
  4. Error Handling

    • Detailed error messages
    • Status callbacks for subscriptions
    • Automatic cleanup on failures

Best Practices

  1. Initialization

    • Initialize once at application start
    • Keep configuration in environment variables
    • Validate configuration before initializing
  2. Authentication

    • Update auth token whenever new claims are received
    • Handle auth errors appropriately
    • Monitor token expiration
  3. Subscriptions

    • Always provide status callbacks
    • Clean up subscriptions when no longer needed
    • Handle reconnection scenarios
  4. Error Handling

    • Log all errors appropriately
    • Provide fallback mechanisms
    • Clean up resources on errors

Examples

See the examples directory for complete usage examples.

Add Package

deno add jsr:@clashon/platform-persistence

Import symbol

import * as platform_persistence from "@clashon/platform-persistence";

---- OR ----

Import directly with a jsr specifier

import * as platform_persistence from "jsr:@clashon/platform-persistence";

Add Package

npx jsr add @clashon/platform-persistence

Import symbol

import * as platform_persistence from "@clashon/platform-persistence";

Add Package

yarn dlx jsr add @clashon/platform-persistence

Import symbol

import * as platform_persistence from "@clashon/platform-persistence";

Add Package

pnpm dlx jsr add @clashon/platform-persistence

Import symbol

import * as platform_persistence from "@clashon/platform-persistence";

Add Package

bunx jsr add @clashon/platform-persistence

Import symbol

import * as platform_persistence from "@clashon/platform-persistence";