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

Original：🇺🇸 English

Translated

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.

1installs

Sourceepicenterhq/epicenter

Added on2026-02-17

NPX Install

npx skill4agent add epicenterhq/epicenter sync-construction-async-property-ui-render-gate-pattern

SKILL.md Content

View Translation Comparison →

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:

typescript

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

So you end up with getter patterns:

typescript

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:

typescript

// 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:

svelte

<!-- +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:

typescript

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>`	`X` with `.whenSynced`

Real-World Example: y-indexeddb

The Yjs ecosystem uses this pattern everywhere:

typescript

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

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

NPX Install

Tags

SKILL.md Content

Sync Construction, Async Property

When to Apply This Pattern

The Problem

The Pattern

The UI Render Gate

Implementation

Before and After

Real-World Example: y-indexeddb

Related Patterns

References