@lucashw68/nsdb 1.0.0-rc.2

package/runtime/stores/createDbStore.ts

@@ -0,0 +1,439 @@
+import { computed, shallowRef, ref, watch } from 'vue'
+import { defineStore, useSupabaseClient, useSupabaseUser } from '#imports'
+import { useSupabaseApi } from '../composables/useSupabaseApi'
+import { isComplexCollectionQuery, sortCollection, stableQueryKey } from '../utils/dataFreshness'
+import type { ListOptions } from '@lucashw68/nsdb/types/list'
+
+export type DbStoreFetchOptions = ListOptions & {
+	merge?: boolean
+	staleTimeMs?: number
+}
+
+export function createDbStore<T extends Record<string, any>>(resource: string, options: {
+	key?: keyof T
+	orderBy?: keyof T
+	defaultSort?: 'asc' | 'desc'
+	staleTimeMs?: number
+	persist?: boolean
+	scopeToUser?: boolean
+}) {
+	const key = options.key || 'id'
+	const orderBy = options.orderBy || key
+	const sortDir = options.defaultSort || 'desc'
+	const defaultStaleTimeMs = options.staleTimeMs ?? 30_000
+	const shouldPersist = options.persist ?? false
+	const shouldScopeToUser = options.scopeToUser ?? true
+
+	return defineStore(`db_${resource}`, () => {
+		const supabase = useSupabaseClient()
+		const supabaseUser = useSupabaseUser()
+		const api = useSupabaseApi()
+		const items = shallowRef<T[]>([])
+		const totalCount = ref<number | null>(null)
+		const loading = ref(false)
+		const error = ref<any>(null)
+		const lastFetchedAt = ref<number | null>(null)
+		const lastQueryKey = ref<string | null>(null)
+		const scopeOwnerId = ref<string | null>(null)
+		const hydrationReady = ref(!shouldPersist || !shouldScopeToUser)
+		const stale = ref(true)
+		const cachedQueries = new Map<string, { rows: T[]; count: number | null; fetchedAt: number }>()
+		const inFlightQueries = new Map<string, Promise<T[]>>()
+		const maxCachedQueries = 20
+		let hydrationValidation: Promise<void> | null = null
+		let currentQuery: ListOptions = getDefaultQuery()
+		let collectionRevision = 0
+		let fetchSequence = 0
+		let subscription: ReturnType<typeof supabase.channel> | null = null
+		let subscriptionOwnerId: string | null = null
+		let realtimeRequested = false
+		let realtimeDisconnected = false
+
+		function resetData() {
+			items.value = []
+			totalCount.value = null
+			loading.value = false
+			error.value = null
+			lastFetchedAt.value = null
+			lastQueryKey.value = null
+			stale.value = true
+			cachedQueries.clear()
+			inFlightQueries.clear()
+			collectionRevision++
+		}
+
+		function reconcileUserScope(userId: string | null) {
+			if (!shouldScopeToUser) return
+			if (scopeOwnerId.value !== userId) {
+				void unsubscribe(false)
+				resetData()
+			}
+			scopeOwnerId.value = userId
+			if (realtimeRequested && userId) queueMicrotask(() => subscribe())
+		}
+
+		function reset() {
+			realtimeRequested = false
+			void unsubscribe(false)
+			resetData()
+			if (shouldScopeToUser) scopeOwnerId.value = supabaseUser.value?.id ?? null
+		}
+
+		function quarantineHydratedState() {
+			if (!shouldPersist || !shouldScopeToUser) {
+				hydrationReady.value = true
+				return Promise.resolve()
+			}
+
+			const hydrated = {
+				items: [...items.value],
+				totalCount: totalCount.value,
+				lastFetchedAt: lastFetchedAt.value,
+				lastQueryKey: lastQueryKey.value,
+				ownerId: scopeOwnerId.value,
+			}
+
+			// Persisted rows must disappear synchronously, before Vue can render them.
+			resetData()
+			scopeOwnerId.value = null
+			hydrationReady.value = false
+
+			hydrationValidation = (async () => {
+				try {
+					const { data, error: userError } = await supabase.auth.getUser()
+					const resolvedUserId = userError ? null : data?.user?.id ?? null
+
+					if (resolvedUserId && hydrated.ownerId === resolvedUserId) {
+						items.value = hydrated.items
+						totalCount.value = hydrated.totalCount
+						lastFetchedAt.value = hydrated.lastFetchedAt
+						lastQueryKey.value = hydrated.lastQueryKey
+					}
+
+					scopeOwnerId.value = resolvedUserId
+			} finally {
+				hydrationReady.value = true
+				hydrationValidation = null
+			}
+		})()
+
+			return hydrationValidation
+		}
+
+		async function waitForHydrationValidation() {
+			if (hydrationValidation) await hydrationValidation
+		}
+
+		if (shouldScopeToUser) {
+			watch(
+				() => supabaseUser.value?.id ?? null,
+				(newUserId) => reconcileUserScope(newUserId),
+				{ immediate: true },
+			)
+		}
+
+		function getItemKey(item: Partial<T> | Record<string, any>) {
+			return item?.[key as string] as string | number | undefined
+		}
+
+		function getDefaultQuery(): ListOptions {
+			return {
+				orderBy: String(orderBy),
+				orderDirection: sortDir,
+				limit: 100,
+				offset: 0,
+			}
+		}
+
+		function getQuerySignature(query: ListOptions) {
+			return stableQueryKey({
+				select: query.select ?? '*',
+				where: query.where ?? null,
+				orderBy: query.orderBy ?? null,
+				orderDirection: query.orderDirection ?? null,
+				orderForeignTable: query.orderForeignTable ?? null,
+				limit: query.limit ?? null,
+				offset: query.offset ?? null,
+				search: query.search ?? null,
+				searchColumns: query.searchColumns ?? [],
+			})
+		}
+
+		const cachedCount = computed(() => items.value.length)
+
+		const mergeItems = (newItems: T[]) => {
+			const map = new Map<string | number | undefined, T>(items.value.map(item => [getItemKey(item), item]))
+			for (const newItem of newItems) {
+				map.set(getItemKey(newItem), newItem)
+			}
+			items.value = Array.from(map.values()).filter(Boolean) as T[]
+		}
+
+		const replaceItems = (newItems: T[]) => {
+			items.value = [...newItems]
+		}
+
+		const addOrUpdate = (item: T) => {
+			const itemKey = getItemKey(item)
+			const index = items.value.findIndex(candidate => getItemKey(candidate) === itemKey)
+			if (index !== -1) {
+				const nextItems = [...items.value]
+				nextItems[index] = item
+				items.value = nextItems
+			}
+			else items.value = [item, ...items.value]
+		}
+
+		const removeLocal = (id: string | number) => {
+			items.value = items.value.filter(item => getItemKey(item) !== id)
+		}
+
+		function rememberQuery(signature: string, entry: { rows: T[]; count: number | null; fetchedAt: number }) {
+			cachedQueries.delete(signature)
+			cachedQueries.set(signature, entry)
+			while (cachedQueries.size > maxCachedQueries) {
+				const oldest = cachedQueries.keys().next().value
+				if (oldest === undefined) break
+				cachedQueries.delete(oldest)
+			}
+		}
+
+		function invalidate() {
+			collectionRevision++
+			cachedQueries.clear()
+			lastQueryKey.value = null
+			stale.value = true
+		}
+
+		function markMutation() {
+			invalidate()
+			if (isComplexCollectionQuery(currentQuery)) totalCount.value = null
+		}
+
+		const getById = (id: string | number) => {
+			return items.value.find(item => getItemKey(item) === id) || null
+		}
+
+		const fetchFromSupabaseInternal = async (query: DbStoreFetchOptions = {}, bypassCache = false) => {
+			await waitForHydrationValidation()
+			reconcileUserScope(supabaseUser.value?.id ?? null)
+			const {
+				merge = false,
+				staleTimeMs = defaultStaleTimeMs,
+				...queryOptions
+			} = query
+			const finalQuery: ListOptions = {
+				...getDefaultQuery(),
+				...queryOptions,
+			}
+			const querySignature = getQuerySignature(finalQuery)
+			currentQuery = finalQuery
+			let cachedQuery = cachedQueries.get(querySignature)
+			const now = Date.now()
+			if (!cachedQuery && lastQueryKey.value === querySignature && lastFetchedAt.value != null) {
+				cachedQuery = { rows: [...items.value], count: totalCount.value, fetchedAt: lastFetchedAt.value }
+			}
+
+			if (!bypassCache && cachedQuery && now - cachedQuery.fetchedAt < staleTimeMs) {
+				if (merge) mergeItems(cachedQuery.rows)
+				else replaceItems(cachedQuery.rows)
+				totalCount.value = cachedQuery.count
+				lastFetchedAt.value = cachedQuery.fetchedAt
+				lastQueryKey.value = querySignature
+				stale.value = false
+				error.value = null
+				rememberQuery(querySignature, cachedQuery)
+				return cachedQuery.rows
+			}
+			const inFlightKey = `${querySignature}:${merge ? 'merge' : 'replace'}`
+			const pending = inFlightQueries.get(inFlightKey)
+			if (!bypassCache && pending) return pending
+
+			const requestId = ++fetchSequence
+			const startingRevision = collectionRevision
+			loading.value = true
+			error.value = null
+
+			const request = (async () => {
+			try {
+				const response = await api.all<T>(resource, finalQuery)
+
+				if (!response.success) {
+					error.value = response.error
+					throw response.error
+				}
+
+				const rows = Array.isArray(response.data) ? response.data : []
+
+				if (requestId === fetchSequence && startingRevision === collectionRevision) {
+					if (merge) mergeItems(rows)
+					else replaceItems(rows)
+					totalCount.value = response.count ?? null
+					lastFetchedAt.value = Date.now()
+					lastQueryKey.value = querySignature
+					stale.value = false
+					rememberQuery(querySignature, { rows, count: response.count ?? null, fetchedAt: Date.now() })
+				}
+
+				return rows
+			} catch (fetchError) {
+				console.error(`[${resource}] fetch error`, fetchError)
+				error.value = fetchError
+				stale.value = true
+				throw fetchError
+			} finally {
+				if (requestId === fetchSequence) loading.value = false
+				inFlightQueries.delete(inFlightKey)
+			}
+			})()
+			inFlightQueries.set(inFlightKey, request)
+			return request
+		}
+		const fetchFromSupabase = (query: DbStoreFetchOptions = {}) => fetchFromSupabaseInternal(query)
+
+		const refresh = (query: DbStoreFetchOptions = {}) => fetchFromSupabaseInternal({ ...currentQuery, ...query }, true)
+
+		const create = async (payload: Partial<T>): Promise<T | null> => {
+			await waitForHydrationValidation()
+			reconcileUserScope(supabaseUser.value?.id ?? null)
+			const response = await api.create<T>(resource, payload)
+
+			if (!response.success) {
+				console.error(`[${resource}] create error`, response.error)
+				throw response.error
+			}
+
+			const data = response.data as T
+			markMutation()
+			if (!isComplexCollectionQuery(currentQuery)) {
+				addOrUpdate(data)
+				items.value = sortCollection(items.value, currentQuery).slice(0, currentQuery.limit ?? 100)
+				if (totalCount.value != null) totalCount.value++
+			}
+			return data
+		}
+
+		const update = async (id: string | number, payload: Partial<T>): Promise<T | null> => {
+			await waitForHydrationValidation()
+			reconcileUserScope(supabaseUser.value?.id ?? null)
+			const response = await api.update<T>(resource, id, payload, { key: String(key) })
+
+			if (!response.success) {
+				console.error(`[${resource}] update error`, response.error)
+				throw response.error
+			}
+
+			const data = Array.isArray(response.data) ? response.data[0] : response.data
+			if (data) {
+				markMutation()
+				if (!isComplexCollectionQuery(currentQuery)) {
+					addOrUpdate(data as T)
+					items.value = sortCollection(items.value, currentQuery)
+				}
+			}
+			return (data as T | undefined) ?? null
+		}
+
+		const remove = async (id: string | number) => {
+			await waitForHydrationValidation()
+			reconcileUserScope(supabaseUser.value?.id ?? null)
+			const response = await api.remove(resource, id, { key: String(key) })
+
+			if (!response.success) {
+				console.error(`[${resource}] delete error`, response.error)
+				throw response.error
+			}
+
+			const existed = !!getById(id)
+			markMutation()
+			removeLocal(id)
+			if (!isComplexCollectionQuery(currentQuery) && existed && totalCount.value != null) totalCount.value--
+		}
+
+		const subscribe = () => {
+			realtimeRequested = true
+			if (typeof window === 'undefined' || subscription) return
+			subscriptionOwnerId = supabaseUser.value?.id ?? null
+
+			subscription = supabase
+				.channel(`public:${resource}`)
+				.on('postgres_changes', {
+					event: '*',
+					schema: 'public',
+					table: resource
+				}, (payload: any) => {
+					if (shouldScopeToUser && subscriptionOwnerId !== (supabaseUser.value?.id ?? null)) return
+					const { eventType, new: newItem, old } = payload
+					invalidate()
+					if (isComplexCollectionQuery(currentQuery)) return
+					if (eventType === 'INSERT' || eventType === 'UPDATE') {
+						addOrUpdate(newItem as T)
+						items.value = sortCollection(items.value, currentQuery)
+					} else if (eventType === 'DELETE') {
+						removeLocal(old?.[key as string])
+					}
+				})
+				.subscribe((status: string, statusError?: unknown) => {
+					if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT' || status === 'CLOSED') {
+						realtimeDisconnected = true
+						stale.value = true
+						if (statusError) error.value = statusError
+					}
+					else if (status === 'SUBSCRIBED' && realtimeDisconnected) {
+						realtimeDisconnected = false
+						invalidate()
+						void refresh().catch(() => {})
+					}
+				})
+
+			console.info(`[${resource}] realtime subscription initialized`)
+		}
+
+		async function unsubscribe(clearIntent = true) {
+			if (clearIntent) realtimeRequested = false
+			const active = subscription
+			subscription = null
+			subscriptionOwnerId = null
+			realtimeDisconnected = false
+			if (!active) return
+			if (typeof (supabase as any).removeChannel === 'function') await (supabase as any).removeChannel(active)
+			else await active.unsubscribe()
+		}
+
+		return {
+			items,
+			totalCount,
+			cachedCount,
+			loading,
+			error,
+			stale,
+			lastFetchedAt,
+			lastQueryKey,
+			scopeOwnerId,
+			hydrationReady,
+			fetchFromSupabase,
+			refresh,
+			invalidate,
+			addOrUpdate,
+			removeLocal,
+			reset,
+			remove,
+			getById,
+			create,
+			update,
+			subscribe,
+			unsubscribe,
+			reconcileUserScope,
+			quarantineHydratedState,
+		}
+	}, {
+		persist: shouldPersist
+			? {
+				pick: ['items', 'totalCount', 'lastFetchedAt', 'lastQueryKey', 'scopeOwnerId'],
+				afterHydrate: ({ store }: { store: { quarantineHydratedState?: () => Promise<void> } }) => {
+					void store.quarantineHydratedState?.()
+				},
+			}
+			: false,
+	} as any)
+}

package/runtime/stores/createSingletonDbStore.ts

@@ -0,0 +1,67 @@
+import { ref } from 'vue'
+import { defineStore } from '#imports'
+
+export interface SingletonStoreOptions<T> {
+    /** Fonction de chargement de la ressource depuis Supabase ou autre */
+    fetch: () => Promise<{ success: boolean; data?: T; error?: any }>
+
+    /** Fonction de mise à jour de la ressource dans la base */
+    update?: (partialData: Partial<T>) => Promise<{ success: boolean; data?: T; error?: any }>
+
+    /** Clé d'identification unique du store */
+    id: string
+
+    /** Activer la persistance locale */
+    persist?: boolean
+}
+
+export function createSingletonStore<T>(options: SingletonStoreOptions<T>) {
+    const {
+        id,
+        fetch,
+        update = async () => ({ success: false, error: 'Update not implemented' }),
+        persist = false
+    } = options
+
+    return defineStore(id, () => {
+        const data = ref<T | null>(null)
+        const loading = ref(false)
+        const error = ref<any>(null)
+
+        const fetchData = async () => {
+            loading.value = true
+            const result = await fetch()
+            loading.value = false
+
+            if (result.success && result.data) {
+                data.value = result.data
+                error.value = null
+            } else {
+                error.value = result.error
+            }
+
+            return result
+        }
+
+        const updateData = async (partialData: Partial<T>) => {
+            const result = await update(partialData)
+
+            if (result.success && result.data) {
+                data.value = result.data
+                error.value = null
+            } else {
+                error.value = result.error
+            }
+
+            return result
+        }
+
+        return {
+            data,
+            loading,
+            error,
+            fetch: fetchData,
+            update: updateData
+        }
+    }, { persist } as any)
+}

package/runtime/utils/dataFreshness.ts

@@ -0,0 +1,47 @@
+import type { ListOptions } from '@lucashw68/nsdb/types/list'
+
+function normalize(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(normalize)
+	if (value && typeof value === 'object') {
+		return Object.fromEntries(
+			Object.entries(value as Record<string, unknown>)
+				.filter(([, entry]) => entry !== undefined)
+				.sort(([left], [right]) => left.localeCompare(right))
+				.map(([key, entry]) => [key, normalize(entry)]),
+		)
+	}
+	return value
+}
+
+export function stableQueryKey(value: unknown): string {
+	return JSON.stringify(normalize(value))
+}
+
+export function isComplexCollectionQuery(query: ListOptions): boolean {
+	return !!(
+		(query.where && Object.keys(query.where).length > 0)
+		|| query.search
+		|| (query.offset ?? 0) > 0
+		|| query.orderForeignTable
+		// Selecting a subset of scalar columns does not change membership. An
+		// embedded PostgREST relation does, and cannot be maintained locally.
+		|| (query.select?.includes('(') ?? false)
+	)
+}
+
+export function sortCollection<T extends Record<string, any>>(
+	rows: T[],
+	query: ListOptions,
+): T[] {
+	if (!query.orderBy || query.orderForeignTable) return [...rows]
+	const direction = query.orderDirection === 'desc' ? -1 : 1
+	const column = query.orderBy
+	return [...rows].sort((left, right) => {
+		const a = left[column]
+		const b = right[column]
+		if (a == null && b == null) return 0
+		if (a == null) return 1
+		if (b == null) return -1
+		return String(a).localeCompare(String(b), undefined, { numeric: true }) * direction
+	})
+}

package/runtime/utils/storage.ts

@@ -0,0 +1,41 @@
+export function normalizePath(path = '') {
+	const segments = path
+		.split('/')
+		.map(part => part.trim())
+		.filter(Boolean)
+
+	if (segments.some(part => part === '.' || part === '..')) {
+		throw new Error('[nsdb:storage] Relative path segments are not allowed.')
+	}
+
+	return segments.join('/')
+}
+
+export function normalizeDirectoryPath(path = '') {
+	return normalizePath(path)
+}
+
+export function normalizeFilePath(path: string) {
+	const normalizedPath = normalizePath(path)
+	if (!normalizedPath) throw new Error('[nsdb:storage] A file path is required.')
+	return normalizedPath
+}
+
+export function joinPath(...parts: Array<string | number | null | undefined>) {
+	return parts
+		.map(part => normalizePath(String(part ?? '')))
+		.filter(Boolean)
+		.join('/')
+}
+
+export function applySearchFilter<T extends { name?: string }>(items: T[], search?: string) {
+	const normalizedSearch = search?.trim().toLowerCase()
+	if (!normalizedSearch) return items
+	return items.filter(item => item.name?.toLowerCase().includes(normalizedSearch))
+}
+
+export function normalizeBucketName(bucketName: string) {
+	const normalizedName = bucketName.trim()
+	if (!normalizedName) throw new Error('[nsdb:storage] A bucket name is required.')
+	return normalizedName
+}

package/scripts/clear.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { parseArgs } from '../helpers/args.js'
+import { loadNsdbConfig } from '../helpers/config.js'
+import {
+	isNsdbGeneratedFile,
+	listGeneratedFiles,
+	removeGeneratedFile,
+} from '../helpers/generated.js'
+
+function configuredTargets(currentWorkingDirectory, config, shouldDeleteStores) {
+	const fileTargets = [config.paths.enums]
+	const directoryTargets = [
+		config.paths.schemas,
+		config.paths.models,
+		config.paths.composables,
+	]
+
+	if (shouldDeleteStores) directoryTargets.push(config.paths.stores)
+
+	return {
+		fileTargets: fileTargets.map(target => path.resolve(currentWorkingDirectory, target)),
+		directoryTargets: [...new Set(directoryTargets.map(target => path.resolve(currentWorkingDirectory, target)))],
+	}
+}
+
+export async function clearGeneratedFiles({
+	currentWorkingDirectory = process.cwd(),
+	parsedArguments = parseArgs(),
+} = {}) {
+	const verbose = parsedArguments.getBool('verbose', false)
+	const dryRun = parsedArguments.getBool('dry-run', false)
+	const shouldDeleteStores = !parsedArguments.getBool('no-stores', false)
+	const { config } = await loadNsdbConfig(
+		currentWorkingDirectory,
+		parsedArguments.get('config', ''),
+	)
+	const targets = configuredTargets(currentWorkingDirectory, config, shouldDeleteStores)
+	const candidates = [
+		...targets.fileTargets.filter(isNsdbGeneratedFile),
+		...targets.directoryTargets.flatMap(listGeneratedFiles),
+	]
+	const uniqueCandidates = [...new Set(candidates)]
+
+	for (const filePath of uniqueCandidates) {
+		removeGeneratedFile(filePath, { dryRun, verbose })
+	}
+
+	if (dryRun) {
+		console.log(`Cleanup preview: ${uniqueCandidates.length} generated file(s) would be removed.`)
+	} else {
+		console.log(`Cleanup completed: ${uniqueCandidates.length} generated file(s) removed.`)
+	}
+
+	return uniqueCandidates
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	clearGeneratedFiles().catch((error) => {
+		console.error('Failed to clear NSDB generated files.')
+		console.error(error)
+		process.exit(1)
+	})
+}