sync-construction-async-property-ui-render-gate-pattern

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:

{#await client.whenSynced} {: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 Aspect Async Construction Sync + whenSynced Module export Can't export directly Export the object Consumer code await getX() everywhere Direct import, sync use UI integration Awkward promise handling Single {#await} gate Type signature Promise X with .whenSynced 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