name: sync-construction-async-property-ui-render-gate-pattern
description: Sync construction with async property pattern. Use when creating clients that need async initialization but must be exportable from modules and usable synchronously in UI components.
metadata:
author: epicenter
version: '1.0'

Sync Construction, Async Property

The initialization of the client is synchronous. The async work is stored as a property you can await, while passing the reference around.

When to Apply This Pattern

Use this when you have:

• Async client initialization (IndexedDB, server connection, file system)
• Module exports that need to be importable without await
• UI components that want sync access to the client
• SvelteKit apps where you want to gate rendering on readiness

Signals you're fighting async construction:

• await getX() patterns everywhere
• Top-level await complaints from bundlers
• Getter functions wrapping singleton access
• Components that can't import a client directly

The Problem

Async constructors can't be exported:

// This doesn't work
export const client = await createClient(); // Top-level await breaks bundlers

So you end up with getter patterns:

let client: Client | null = null;

export async function getClient() {
    if (!client) {
        client = await createClient();
    }
    return client;
}

// Every consumer must await
const client = await getClient();

Every call site needs await. You're passing promises around instead of objects.

The Pattern

Make construction synchronous. Attach async work to the object:

// client.ts
export const client = createClient();

// Sync access works immediately
client.save(data);
client.load(id);

// Await the async work when you need to
await client.whenSynced;

Construction returns immediately. The async initialization (loading from disk, connecting to servers) happens in the background and is tracked via whenSynced.

The UI Render Gate

In Svelte, await once at the root:

<!-- +layout.svelte -->
<script>
    import { client } from '$lib/client';
</script>

{#await client.whenSynced}
    <LoadingSpinner />
{:then}
    {@render children?.()}
{/await}

The gate guarantees: by the time any child component's script runs, the async work is complete. Children use sync access without checking readiness.

Implementation

The withCapabilities() fluent builder attaches async work to a sync-constructed object:

function createClient() {
    const state = initializeSyncState();

    return {
        save(data) {
            /* sync method */
        },
        load(id) {
            /* sync method */
        },

        withCapabilities({ persistence }) {
            const whenSynced = persistence(state);
            return Object.assign(this, { whenSynced });
        },
    };
}

// Usage
export const client = createClient().withCapabilities({
    persistence: (state) => loadFromIndexedDB(state),
});

Before and After

Real-World Example: y-indexeddb

The Yjs ecosystem uses this pattern everywhere:

const provider = new IndexeddbPersistence('my-db', doc);
// Constructor returns immediately

provider.on('update', handleUpdate); // Sync access works

await provider.whenSynced; // Wait when you need to

They never block construction. The async work is always deferred to a property you can await.

Related Patterns

• Lazy Singleton — when you need race-condition-safe lazy initialization
• Don't Use Parallel Maps — attach state to instances instead of tracking separately

References

• Full article — detailed explanation with diagrams
• Comprehensive guide — 480-line deep dive