@korajs/svelte 1.0.0-beta.12 → 1.0.0-beta.14

package/src/composables/use-rich-text.ts

@@ -0,0 +1,106 @@
+import { asRichTextSyncEngine, createRichTextController } from '@korajs/store'
+import type { AwarenessUser } from '@korajs/sync'
+import { onDestroy } from 'svelte'
+import { type Readable, get, readable } from 'svelte/store'
+import { getKoraContext } from '../context'
+import type { UseRichTextResult } from '../types'
+
+export interface UseRichTextOptions {
+	user?: AwarenessUser
+	useDocChannel?: boolean
+}
+
+/**
+ * Binds a richtext field to a shared Yjs document for editor integration.
+ *
+ * Must be called during component initialization. For reactive target changes,
+ * use {@link KoraRichText} instead.
+ */
+export function createRichTextBinding(
+	collectionName: string,
+	recordId: string,
+	fieldName: string,
+	options?: UseRichTextOptions,
+): UseRichTextResult & { subscribe: Readable<UseRichTextResult>['subscribe'] } {
+	const { store, syncEngine } = getKoraContext()
+
+	const controller = createRichTextController({
+		collection: store.collection(collectionName),
+		collectionName,
+		recordId,
+		fieldName,
+		store,
+		syncEngine: asRichTextSyncEngine(syncEngine),
+		useDocChannel: options?.useDocChannel,
+		user: options?.user,
+	})
+
+	onDestroy(() => {
+		controller.destroy()
+	})
+
+	const resultStore = readable<UseRichTextResult>(buildResult(controller), (set) => {
+		const sync = (): void => {
+			set(buildResult(controller))
+		}
+		sync()
+		return controller.subscribe(sync)
+	})
+
+	return {
+		get doc() {
+			return controller.doc
+		},
+		get text() {
+			return controller.text
+		},
+		undo: () => controller.undo(),
+		redo: () => controller.redo(),
+		get ready() {
+			return get(resultStore).ready
+		},
+		get error() {
+			return get(resultStore).error
+		},
+		get canUndo() {
+			return get(resultStore).canUndo
+		},
+		get canRedo() {
+			return get(resultStore).canRedo
+		},
+		get cursors() {
+			return get(resultStore).cursors
+		},
+		setCursor: (anchor: number, head: number) => controller.setCursor(anchor, head),
+		clearCursor: () => controller.clearCursor(),
+		get hasUnsavedChanges() {
+			return get(resultStore).hasUnsavedChanges
+		},
+		retrySave: () => controller.retrySave(),
+		getUnsavedState: () => controller.getUnsavedState(),
+		subscribe: resultStore.subscribe,
+	}
+}
+
+/** @alias createRichTextBinding */
+export const useRichText = createRichTextBinding
+
+function buildResult(controller: ReturnType<typeof createRichTextController>): UseRichTextResult {
+	const snapshot = controller.getSnapshot()
+	return {
+		doc: controller.doc,
+		text: controller.text,
+		undo: () => controller.undo(),
+		redo: () => controller.redo(),
+		ready: snapshot.ready,
+		error: snapshot.error,
+		canUndo: snapshot.canUndo,
+		canRedo: snapshot.canRedo,
+		cursors: [...snapshot.cursors],
+		setCursor: (anchor, head) => controller.setCursor(anchor, head),
+		clearCursor: () => controller.clearCursor(),
+		hasUnsavedChanges: snapshot.hasUnsavedChanges,
+		retrySave: () => controller.retrySave(),
+		getUnsavedState: () => controller.getUnsavedState(),
+	}
+}

package/src/composables/use-sync-status.ts

@@ -0,0 +1,30 @@
+import { OFFLINE_SYNC_STATUS, createSyncStatusController } from '@korajs/sync'
+import type { SyncStatusInfo } from '@korajs/sync'
+import { type Readable, readable } from 'svelte/store'
+import { getKoraContext } from '../context'
+
+/**
+ * Readable store of sync engine status.
+ */
+export function createSyncStatusStore(): Readable<SyncStatusInfo> {
+	const { syncEngine, subscribeSyncStatus, events } = getKoraContext()
+
+	return readable<SyncStatusInfo>(OFFLINE_SYNC_STATUS, (set) => {
+		const controller = createSyncStatusController({
+			syncEngine,
+			subscribeSyncStatus,
+			events: subscribeSyncStatus ? null : events,
+		})
+		set(controller.getSnapshot())
+		const unsubscribe = controller.subscribe(() => {
+			set(controller.getSnapshot())
+		})
+		return () => {
+			unsubscribe()
+			controller.destroy()
+		}
+	})
+}
+
+/** Alias for {@link createSyncStatusStore}. */
+export const useSyncStatus = createSyncStatusStore

package/src/context.ts

@@ -0,0 +1,66 @@
+import { KoraError } from '@korajs/core'
+import { QueryStoreCache } from '@korajs/store'
+import { getContext, setContext } from 'svelte'
+import type { KoraAppLike, KoraContextValue } from './types'
+
+// Registered (Symbol.for) keys: the .svelte components are compiled from src/ by the app
+// (the "svelte" export condition) while helpers such as getCollection come from dist/, so
+// two copies of this module exist in every app. Module-local Symbol() keys made the
+// provider's context invisible to the helpers ("Kora context missing").
+const koraContextKey = Symbol.for('@korajs/svelte:context')
+const koraAppContextKey = Symbol.for('@korajs/svelte:app')
+
+export function setKoraContext(value: KoraContextValue): void {
+	setContext(koraContextKey, value)
+}
+
+export function getKoraContext(): KoraContextValue {
+	const context = getContext<KoraContextValue | undefined>(koraContextKey)
+	if (!context) {
+		throw new KoraError(
+			'Kora context missing. Wrap your app with <KoraProvider app={kora}> or <KoraStoreProvider store={store}>.',
+			'KORA_NOT_PROVIDED',
+			{ fix: 'Wrap your app with <KoraProvider app={kora}> or <KoraStoreProvider store={store}>.' },
+		)
+	}
+	return context
+}
+
+/** @deprecated Use {@link setKoraContext} via {@link KoraProvider} or {@link KoraStoreProvider}. */
+export function setKoraAppContext(koraApp: KoraAppLike): void {
+	setContext(koraAppContextKey, koraApp)
+}
+
+/** @deprecated Use {@link getKoraContext} and {@link getApp}. */
+export function getKoraApp(): KoraAppLike {
+	const app = getContext<KoraAppLike | undefined>(koraAppContextKey)
+	if (!app) {
+		throw new KoraError(
+			'getKoraApp() requires setKoraAppContext(koraApp) on an ancestor.',
+			'KORA_NOT_PROVIDED',
+		)
+	}
+	return app
+}
+
+/**
+ * Initialize Kora provider context after `app.ready`.
+ *
+ * @deprecated Prefer {@link KoraProvider} or {@link KoraStoreProvider} in root layout.
+ */
+export async function initKoraProvider(app: KoraAppLike): Promise<KoraContextValue> {
+	await app.ready
+	const queryStoreCache =
+		typeof app.getQueryStoreCache === 'function' ? app.getQueryStoreCache() : new QueryStoreCache()
+	const value: KoraContextValue = {
+		store: app.getStore(),
+		syncEngine: app.getSyncEngine(),
+		app,
+		events: app.events ?? null,
+		subscribeSyncStatus: app.sync?.subscribeStatus ?? null,
+		queryStoreCache,
+	}
+	setKoraContext(value)
+	setKoraAppContext(app)
+	return value
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+export type {
+	KoraAppHandle,
+	KoraAppLike,
+	KoraContextValue,
+	UseMutationOptions,
+	UseMutationResult,
+	QueryState,
+	UseQueryOptions,
+	UseRichTextResult,
+} from './types'
+
+export {
+	getKoraApp,
+	getKoraContext,
+	initKoraProvider,
+	setKoraAppContext,
+	setKoraContext,
+} from './context'
+
+export {
+	createQueryStateStore,
+	createQueryStore,
+	useQuery,
+	useQueryState,
+} from './stores/query-store'
+export type { QueryInput } from './stores/query-store'
+export { createMutation, useMutation } from './composables/use-mutation'
+export { createSyncStatusStore, useSyncStatus } from './composables/use-sync-status'
+export { getApp, useApp } from './composables/use-app'
+export { getCollection, useCollection } from './composables/use-collection'
+export { createRichTextBinding, useRichText } from './composables/use-rich-text'
+export type { UseRichTextOptions } from './composables/use-rich-text'
+export { applyPresence, usePresence } from './composables/use-presence'
+export { createCollaboratorsStore, useCollaborators } from './composables/use-collaborators'

package/src/stores/query-store.ts

@@ -0,0 +1,186 @@
+import type { CollectionRecord, QueryBuilder, QueryStore, QueryStoreCache } from '@korajs/store'
+import { assertQueryReady, queryKey } from '@korajs/store'
+import { type Readable, readable } from 'svelte/store'
+import { getKoraContext } from '../context'
+import type { QueryState, UseQueryOptions } from '../types'
+
+const EMPTY_ARRAY: readonly unknown[] = Object.freeze([])
+
+/** A query input: a builder, or a readable store of one (null disables). */
+export type QueryInput<T> = QueryBuilder<T> | Readable<QueryBuilder<T> | null | undefined>
+
+function isQueryBuilder<T>(input: QueryInput<T>): input is QueryBuilder<T> {
+	return typeof (input as { getDescriptor?: unknown }).getDescriptor === 'function'
+}
+
+function isReadable<V>(input: V | Readable<V>): input is Readable<V> {
+	return (
+		typeof input === 'object' &&
+		input !== null &&
+		typeof (input as { subscribe?: unknown }).subscribe === 'function'
+	)
+}
+
+/** The STORE-12 error channel of a QueryStore, read structurally (older store builds lack it). */
+function readQueryError(queryStore: QueryStore<unknown>): Error | null {
+	const channel = queryStore as unknown as { getError?: () => Error | null }
+	return typeof channel.getError === 'function' ? channel.getError() : null
+}
+
+/**
+ * Follows the query and `enabled` inputs (values or readable stores), holding one
+ * ref-counted QueryStore per descriptor and switching when the descriptor changes
+ * (DX-7). Returns the teardown.
+ */
+function followQuery<T>(
+	cache: QueryStoreCache,
+	query: QueryInput<T>,
+	options: UseQueryOptions | undefined,
+	emit: (state: QueryState<T>) => void,
+): () => void {
+	let current: QueryBuilder<T> | null = isQueryBuilder(query) ? query : null
+	const enabledInput = options?.enabled
+	let enabled = isReadable(enabledInput) ? true : enabledInput !== false
+	let activeKey: string | null = null
+	let release: (() => void) | null = null
+	let state: QueryState<T> = {
+		data: EMPTY_ARRAY as readonly T[],
+		error: null,
+		ready: false,
+	}
+
+	const publish = (next: QueryState<T>): void => {
+		if (next.data === state.data && next.error === state.error && next.ready === state.ready) {
+			return
+		}
+		if (next.error && next.error !== state.error) options?.onError?.(next.error)
+		state = next
+		emit(state)
+	}
+
+	const apply = (): void => {
+		const key = enabled && current ? queryKey(current.getDescriptor()) : null
+		if (key === activeKey) return
+		release?.()
+		release = null
+		activeKey = key
+		if (!key || !current) {
+			publish({ data: EMPTY_ARRAY as readonly T[], error: null, ready: false })
+			return
+		}
+		const builder = current
+		assertQueryReady(builder as QueryBuilder<unknown>)
+		const queryStore = cache.getOrCreate(builder)
+		const sync = (): void => {
+			const loaded = queryStore.hasSnapshot()
+			publish({
+				// A descriptor switch keeps the previous rows until the new query answers.
+				data: loaded ? queryStore.getSnapshot() : state.data,
+				error: readQueryError(queryStore as QueryStore<unknown>),
+				ready: loaded,
+			})
+		}
+		const unsubscribe = queryStore.subscribe(sync)
+		sync()
+		release = () => {
+			unsubscribe()
+			cache.release(builder as QueryBuilder<unknown>)
+		}
+	}
+
+	const stops: Array<() => void> = []
+	if (!isQueryBuilder(query)) {
+		stops.push(
+			query.subscribe((next) => {
+				current = next ?? null
+				apply()
+			}),
+		)
+	}
+	if (isReadable(enabledInput)) {
+		stops.push(
+			enabledInput.subscribe((next) => {
+				enabled = next !== false
+				apply()
+			}),
+		)
+	}
+	apply()
+
+	return () => {
+		for (const stop of stops) stop()
+		release?.()
+		release = null
+		activeKey = null
+	}
+}
+
+/**
+ * Create a Svelte readable store of a Kora query's rows.
+ *
+ * The query and `enabled` may be plain values or readable stores: pass a store (for
+ * example a `derived` of your filter) and the rows follow it, re-subscribing when the
+ * query's descriptor changes. A failed query is reported through `options.onError`,
+ * or `console.error` without one; use {@link createQueryStateStore} to render it.
+ *
+ * @param query - A query builder, or a readable store of one (null disables)
+ * @param options - `enabled` (value or readable store; default true) and `onError`
+ * @returns A readable store of the current rows
+ *
+ * @example
+ * ```ts
+ * const filter = writable(false)
+ * const todos = createQueryStore(derived(filter, (done) => app.todos.where({ completed: done })))
+ * ```
+ */
+export function createQueryStore<T = CollectionRecord>(
+	query: QueryInput<T>,
+	options?: UseQueryOptions,
+): Readable<readonly T[]> {
+	const { queryStoreCache } = getKoraContext()
+	const reporting: UseQueryOptions = {
+		...options,
+		onError:
+			options?.onError ??
+			((failure: Error) => {
+				// Never swallowed: without a handler the failure is at least logged.
+				reportUnhandled(failure)
+			}),
+	}
+	return readable<readonly T[]>(EMPTY_ARRAY as readonly T[], (set) =>
+		followQuery(queryStoreCache, query, reporting, (state) => set(state.data)),
+	)
+}
+
+/**
+ * Like {@link createQueryStore}, but the store holds `{ data, error, ready }`.
+ *
+ * @param query - A query builder, or a readable store of one
+ * @param options - `enabled` and `onError`
+ * @returns A readable store of the query state
+ */
+export function createQueryStateStore<T = CollectionRecord>(
+	query: QueryInput<T>,
+	options?: UseQueryOptions,
+): Readable<QueryState<T>> {
+	const { queryStoreCache } = getKoraContext()
+	const initial: QueryState<T> = { data: EMPTY_ARRAY as readonly T[], error: null, ready: false }
+	return readable<QueryState<T>>(initial, (set) =>
+		followQuery(queryStoreCache, query, options, set),
+	)
+}
+
+/**
+ * Logs a query failure nobody handles. Read through globalThis because this package
+ * builds without DOM or Node typings.
+ */
+function reportUnhandled(failure: Error): void {
+	const host = globalThis as { console?: { error(...args: unknown[]): void } }
+	host.console?.error('[Kora] createQueryStore failed:', failure)
+}
+
+/** Alias for {@link createQueryStore}. */
+export const useQuery = createQueryStore
+
+/** Alias for {@link createQueryStateStore}. */
+export const useQueryState = createQueryStateStore

package/src/types.ts

@@ -0,0 +1,71 @@
+import type {
+	KoraAppLike as CoreKoraAppLike,
+	KoraContextValue as CoreKoraContextValue,
+	UseMutationOptions as CoreUseMutationOptions,
+	UseQueryOptions as CoreUseQueryOptions,
+	UseMutationResultBase,
+} from '@korajs/core/bindings'
+import type { QueryStoreCache, Store } from '@korajs/store'
+import type { CursorInfo, SyncEngine, SyncStatusInfo } from '@korajs/sync'
+import type { Readable } from 'svelte/store'
+import type * as Y from 'yjs'
+
+export type KoraAppLike = CoreKoraAppLike<Store, SyncEngine, QueryStoreCache>
+export type KoraContextValue = CoreKoraContextValue<Store, SyncEngine, QueryStoreCache>
+/** Options for `createQueryStore` and `createQueryStateStore`. */
+export interface UseQueryOptions extends Omit<CoreUseQueryOptions, 'enabled'> {
+	/** When false, the query subscription is disabled. A value or a readable store. Defaults to true. */
+	enabled?: boolean | Readable<boolean>
+	/** Called when the query fails (STORE-12). `createQueryStore` logs to `console.error` without it. */
+	onError?: (error: Error) => void
+}
+
+/** Value of `createQueryStateStore`. */
+export interface QueryState<T> {
+	/** The current rows (the last good rows while `error` is set). */
+	data: readonly T[]
+	/** The query's failure, or null. Cleared when results flow again. */
+	error: Error | null
+	/** False until the first result for the current query arrived. */
+	ready: boolean
+}
+export type UseMutationOptions<
+	TData,
+	TArgs extends unknown[],
+	TContext = void,
+> = CoreUseMutationOptions<TData, TArgs, TContext>
+
+export interface UseMutationResult<TData, TArgs extends unknown[]>
+	extends UseMutationResultBase<TData, TArgs> {
+	subscribeLoading: (fn: (value: boolean) => void) => () => void
+	subscribeError: (fn: (value: Error | null) => void) => () => void
+	readonly loading: boolean
+	readonly isLoading: boolean
+	readonly error: Error | null
+}
+
+/** @deprecated Use {@link KoraAppLike}. */
+export type KoraAppHandle = KoraAppLike
+
+export interface UseRichTextResult {
+	doc: Y.Doc
+	text: Y.Text
+	undo: () => void
+	redo: () => void
+	canUndo: boolean
+	canRedo: boolean
+	ready: boolean
+	error: Error | null
+	cursors: CursorInfo[]
+	setCursor: (anchor: number, head: number) => void
+	clearCursor: () => void
+	/**
+	 * True while local edits are not saved yet (a save pending or refused; see
+	 * `error`). The edits stay in the document and the next edit saves them again.
+	 */
+	hasUnsavedChanges: boolean
+	/** Save the document now, for example after a refused save. */
+	retrySave: () => Promise<void>
+	/** The full document state while edits are unsaved (for a recovery copy), else null. */
+	getUnsavedState: () => Uint8Array | null
+}