feat(react): add usePGliteOptional for use outside a provider

[claygeo]

Problem

Calling usePGlite() without a <PGliteProvider> ancestor throws:

Error: No PGlite instance found, use PGliteProvider to provide one

When the database is created asynchronously (lazy load, code-split, optional feature), components can render before the provider mounts, and the throw crashes the tree. This is issue #878, with a second report in the thread.

Approach

This revision keeps usePGlite() exactly as-is instead of changing its return type. usePGlite(): T still throws when no provider is mounted, so:

• every existing call site keeps working,
• the documented const db = usePGlite(); db.query(...) pattern still type-checks,
• the existing provider.test-d.tsx contract expectTypeOf(usePGlite()).toEqualTypeOf<T>() stays green.

It adds an opt-in escape hatch instead:

• usePGliteOptional(): T | null returns null rather than throwing when there is no provider. makePGliteProvider() returns it too, so typed providers get a typed optional hook.
• Live query hooks: useLiveQueryImpl now resolves the db with usePGliteOptional(). The string-query branch clears results and skips the subscription (reporting undefined) until a provider mounts, then subscribes automatically since db is in the effect deps. The LiveQuery and promise overloads are unchanged; they never needed the context db.

Tests / docs

• provider.test.tsx: usePGlite() still throws outside a provider; usePGliteOptional() returns null, does not throw, and honors an explicit db argument.
• provider.test-d.tsx: adds expectTypeOf(usePGliteOptional()).toEqualTypeOf<T | null>() plus the wrong-extension @ts-expect-error, alongside the unchanged usePGlite() assertion.
• Docs + README: new usePGliteOptional section.
• Changeset: minor bump for @electric-sql/pglite-react.

Closes #878.

[claygeo]

Friendly nudge on this one, and a heads-up that I have reworked it since it was first opened.

I rebased onto current main and changed the approach to be non-breaking. usePGlite() is now left exactly as-is (still returns T, still throws outside a provider), so existing call sites and the provider.test-d.tsx type contract are untouched. The fix is now an opt-in usePGliteOptional(): T | null hook, plus the string-query form of useLiveQuery/useLiveIncrementalQuery returning undefined instead of throwing until a provider mounts. Tests, docs, and a changeset are included.

This resolves #878 (two people hit it). Happy to rename the hook or split the docs change out if you'd prefer. Would appreciate a review when you have a moment.