HyperbasisHyperbasisDocs
Home

Configuration

Configure HBStorage behavior with HBStorageConfig.

Overview

public struct HBStorageConfig {
    public let backend: HBBackend
    public let syncStrategy: HBSyncStrategy
    public let compression: HBCompressionLevel
}

Default Configuration

let storage = HBStorage(config: .default)

// Equivalent to:
let storage = HBStorage(config: HBStorageConfig(
    backend: .localOnly,
    syncStrategy: .manual,
    compression: .balanced
))

Backend Options

public enum HBBackend {
    case localOnly
    case supabase(url: String, anonKey: String)
}

Local Only

No cloud sync. Data is stored only on the device.

let config = HBStorageConfig(
    backend: .localOnly,
    syncStrategy: .manual,
    compression: .balanced
)

Supabase

Enable cloud sync with Supabase.

let config = HBStorageConfig(
    backend: .supabase(
        url: "https://your-project.supabase.co",
        anonKey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    ),
    syncStrategy: .onSave,
    compression: .balanced
)
Note

Find your Supabase URL and anon key in your Supabase project dashboard under Settings > API.

Sync Strategy

public enum HBSyncStrategy {
    case manual
    case onSave
}

Manual

Only sync when sync() is explicitly called:

let config = HBStorageConfig(
    backend: .supabase(url: url, anonKey: key),
    syncStrategy: .manual,
    compression: .balanced
)

// Later...
try await storage.sync()

Use manual sync when:

  • •You want to batch sync operations
  • •Network conditions are poor
  • •You want user control over sync timing

On Save

Sync immediately after each save operation:

let config = HBStorageConfig(
    backend: .supabase(url: url, anonKey: key),
    syncStrategy: .onSave,
    compression: .balanced
)

Use onSave sync when:

  • •Real-time sync is important
  • •Network is reliable
  • •You want automatic cloud backup
Tip

With .onSave, if cloud sync fails, the operation is queued for retry. Local saves always succeed.

Compression Level

public enum HBCompressionLevel {
    case none
    case balanced
}

None

No compression. Faster but larger files.

let config = HBStorageConfig(
    backend: .localOnly,
    syncStrategy: .manual,
    compression: .none
)

Use no compression when:

  • •Storage space is not a concern
  • •CPU is limited
  • •World maps are small

Balanced

Default zlib compression. ~40% size reduction.

let config = HBStorageConfig(
    backend: .localOnly,
    syncStrategy: .manual,
    compression: .balanced
)

Use balanced compression when:

  • •Storage space matters
  • •Cloud sync is enabled (reduces upload time)
  • •Normal usage

Configuration Examples

Development (local only, no compression)

let devConfig = HBStorageConfig(
    backend: .localOnly,
    syncStrategy: .manual,
    compression: .none
)

Production (cloud sync, auto-sync, compressed)

let prodConfig = HBStorageConfig(
    backend: .supabase(
        url: Environment.supabaseUrl,
        anonKey: Environment.supabaseAnonKey
    ),
    syncStrategy: .onSave,
    compression: .balanced
)

Offline-first (cloud backup, manual sync)

let offlineConfig = HBStorageConfig(
    backend: .supabase(url: url, anonKey: key),
    syncStrategy: .manual,
    compression: .balanced
)

// Sync when user requests or network becomes available
func syncWhenReady() async {
    guard NetworkMonitor.isConnected else { return }
    try? await storage.sync()
}

Convenience Initializers

extension HBStorageConfig {
    // Quick cloud setup
    public static func supabase(url: String, anonKey: String) -> HBStorageConfig {
        HBStorageConfig(
            backend: .supabase(url: url, anonKey: anonKey),
            syncStrategy: .onSave,
            compression: .balanced
        )
    }
}

// Usage
let storage = HBStorage(config: .supabase(
    url: "https://xxx.supabase.co",
    anonKey: "eyJ..."
))

Next Steps