@lucashw68/nsdb 1.0.0-rc.2

package/runtime/composables/useSupabaseModels.ts

@@ -0,0 +1,412 @@
+import { useSupabaseApi } from './useSupabaseApi'
+import { useSupabaseClient, useSupabaseUser } from '#imports'
+import type { ModelHandle, ModelMutationTarget, ModelQuery } from '@lucashw68/nsdb/types/model'
+import type { OrderDirection } from '@lucashw68/nsdb/types/list'
+import type { Ref } from 'vue'
+import { computed, isRef, ref, watch } from 'vue'
+import { isComplexCollectionQuery, sortCollection } from '../utils/dataFreshness'
+
+type MutationPayload = Record<string, unknown> | Record<string, unknown>[]
+
+export interface StoreLike<T, TInsert = Partial<T>, TUpdate = Partial<T>> {
+	items: Ref<T[]> | T[]
+	totalCount?: Ref<number | null> | number | null
+	loading?: Ref<boolean> | boolean
+	error?: Ref<unknown> | unknown
+	stale?: Ref<boolean> | boolean
+	getById: (id: string | number) => T | null
+	create: (payload: TInsert) => Promise<T | null>
+	update: (id: string | number, payload: TUpdate) => Promise<T | null>
+	remove: (id: string | number) => void | Promise<void>
+	fetchFromSupabase: (query?: any) => Promise<T[]>
+	subscribe?: () => void
+	unsubscribe?: () => void | Promise<void>
+	refresh?: (query?: any) => Promise<T[]>
+	invalidate?: () => void
+}
+
+type Options<T, TInsert, TUpdate, TPrimaryKey extends Extract<keyof T, string>> =
+	| boolean
+	| { store?: boolean; storeCreator?: () => StoreLike<T, TInsert, TUpdate>; primaryKey?: TPrimaryKey }
+
+export type { ModelHandle, ModelQuery } from '@lucashw68/nsdb/types/model'
+
+/**
+ * Résultat normalisé pour l'order.
+ */
+type NormalizedOrder = {
+	orderBy: string
+	orderDirection: OrderDirection
+	orderForeignTable?: string
+}
+
+function normalizeStoreItems<T>(store: { items: Ref<T[]> | T[] }): Ref<T[]> {
+	if (isRef(store.items)) return store.items
+
+	return computed({
+		get: () => store.items as T[],
+		set: (value) => {
+			;(store as any).items = value
+		},
+	})
+}
+
+function normalizeStoreTotalCount(store: { totalCount?: Ref<number | null> | number | null }): Ref<number | null> {
+	if (isRef(store.totalCount)) return store.totalCount
+
+	return computed({
+		get: () => typeof store.totalCount === 'number' ? store.totalCount : null,
+		set: (value) => {
+			;(store as any).totalCount = value
+		},
+	})
+}
+
+function normalizeStoreRef<T>(store: Record<string, any>, key: string, fallback: T): Ref<T> {
+	if (isRef(store[key])) return store[key] as Ref<T>
+	return computed({
+		get: () => (store[key] ?? fallback) as T,
+		set: value => { store[key] = value },
+	})
+}
+
+function parseOrderPath(path: string): { foreignTable?: string; column: string } {
+	if (!path.includes('.')) return { column: path }
+
+	const parts = path.split('.').filter(Boolean)
+	if (parts.length === 2) {
+		const foreignTable = parts[0]
+		const column = parts[1]
+		if (!foreignTable || !column) return { column: path }
+		return { foreignTable, column }
+	}
+
+	// cas non supporté proprement (ex: a.b.c)
+	return { column: path }
+}
+
+function normalizeOrder(
+	rawOrderBy: ModelQuery<string, string>['orderBy'],
+	rawOrderDirection?: OrderDirection,
+	rawOrderForeignTable?: string,
+	defaultOrderBy: string = 'id',
+): NormalizedOrder {
+	let orderBy = defaultOrderBy
+	let orderDirection: OrderDirection = rawOrderDirection ?? 'asc'
+	let orderForeignTable: string | undefined = rawOrderForeignTable
+
+	if (typeof rawOrderBy === 'string') {
+		const parsed = parseOrderPath(rawOrderBy)
+		orderBy = parsed.column
+		orderForeignTable = parsed.foreignTable ?? rawOrderForeignTable
+		return { orderBy, orderDirection, orderForeignTable }
+	}
+
+	if (rawOrderBy && typeof rawOrderBy === 'object') {
+		const [rawColumn, direction] = Object.entries(rawOrderBy)[0] as [
+			string,
+			OrderDirection | undefined
+		]
+		const parsed = parseOrderPath(rawColumn)
+
+		orderBy = parsed.column
+		orderForeignTable = parsed.foreignTable ?? rawOrderForeignTable
+		orderDirection = direction ?? rawOrderDirection ?? 'asc'
+
+		return { orderBy, orderDirection, orderForeignTable }
+	}
+
+	return { orderBy, orderDirection, orderForeignTable }
+}
+
+/**
+ * Unified CRUD abstraction over a Supabase table.
+ */
+export function useSupabaseModel<
+	TRow,
+	TInsert = Partial<TRow>,
+	TUpdate = Partial<TRow>,
+	TPrimaryKey extends Extract<keyof TRow, string> = Extract<keyof TRow, string>,
+>(
+	modelName: string,
+	opts: Options<TRow, TInsert, TUpdate, TPrimaryKey> = false
+): ModelHandle<TRow, TInsert, TUpdate, TPrimaryKey> {
+	const useStore = typeof opts === 'boolean' ? opts : !!opts.store
+	const storeCreator =
+		typeof opts === 'object' && opts.store ? opts.storeCreator : undefined
+	const primaryKey = typeof opts === 'object' ? opts.primaryKey ?? 'id' : 'id'
+	type RowQuery = ModelQuery<string, Extract<keyof TRow, string>>
+	type MutationTarget = ModelMutationTarget<TRow, TPrimaryKey>
+
+	const resolveMutationTarget = (target: MutationTarget, operation: 'update' | 'remove'): string | number => {
+		const value = typeof target === 'object' && target !== null
+			? (target as Record<string, unknown>)[primaryKey]
+			: target
+
+		if (value === null || value === undefined) {
+			throw new Error(`Cannot ${operation} "${modelName}": target is missing primary key "${primaryKey}".`)
+		}
+
+		return value as string | number
+	}
+
+	// ############################################################
+	// # STORE MODE (Pinia / offline)
+	// ############################################################
+	if (useStore) {
+		if (!storeCreator) {
+			throw new Error(
+				`❌ useSupabaseModel("${modelName}", { store: true }) requires a storeCreator`
+			)
+		}
+
+		const store = storeCreator()
+		const noOp = () => {}
+		const storeItems = normalizeStoreItems(store)
+		const totalCount = normalizeStoreTotalCount(store)
+		const loading = normalizeStoreRef<boolean>(store as any, 'loading', false)
+		const error = normalizeStoreRef<unknown>(store as any, 'error', null)
+		const stale = normalizeStoreRef<boolean>(store as any, 'stale', true)
+
+		const getById = async (id: string | number) =>
+			(store.getById(id) as TRow | null) ?? null
+		const create = async (payload: TInsert): Promise<TRow> => {
+			const created = await store.create(payload)
+			if (created === null || created === undefined) {
+				throw new Error(`Cannot create "${modelName}": Supabase returned no row.`)
+			}
+			return created
+		}
+		const update = (target: MutationTarget, payload: TUpdate) =>
+			store.update(resolveMutationTarget(target, 'update'), payload)
+		const remove = async (target: MutationTarget) => {
+			await store.remove(resolveMutationTarget(target, 'remove'))
+		}
+		const fetch = async (query?: RowQuery) =>
+			(await store.fetchFromSupabase(query)) as TRow[]
+		const refresh = async (query?: RowQuery) => store.refresh
+			? await store.refresh(query) as TRow[]
+			: await store.fetchFromSupabase(query) as TRow[]
+		const invalidate = store.invalidate ?? noOp
+		const subscribe = store.subscribe ?? noOp
+		const unsubscribe = store.unsubscribe ?? noOp
+
+		return {
+			items: storeItems,
+			totalCount,
+			loading,
+			error,
+			stale,
+			getById,
+			create,
+			update,
+			remove,
+			fetch,
+			refresh,
+			invalidate,
+			subscribe,
+			unsubscribe,
+		}
+	}
+
+	// ############################################################
+	// # API MODE (stateless)
+	// ############################################################
+	const api = useSupabaseApi()
+	const supabase = useSupabaseClient()
+	const supabaseUser = useSupabaseUser()
+	const items = ref<TRow[]>([])
+	const typedItems = items as unknown as Ref<TRow[]>
+	const totalCount = ref<number | null>(null)
+	const loading = ref(false)
+	const error = ref<unknown>(null)
+	const stale = ref(true)
+	let fetchSequence = 0
+	let collectionRevision = 0
+	let currentQuery: RowQuery = {}
+	let subscription: ReturnType<typeof supabase.channel> | null = null
+	let subscriptionOwnerId: string | null = null
+	const normalizedCurrentQuery = () => {
+		const order = normalizeOrder(currentQuery.orderBy, currentQuery.orderDirection, currentQuery.orderForeignTable, primaryKey)
+		return { ...currentQuery, ...order }
+	}
+
+	const itemKey = (item: TRow) => (item as Record<string, unknown>)[primaryKey]
+	const addOrUpdate = (item: TRow) => {
+		const id = itemKey(item)
+		const index = typedItems.value.findIndex(candidate => itemKey(candidate) === id)
+		if (index < 0) typedItems.value = [item, ...typedItems.value]
+		else {
+			const next = [...typedItems.value]
+			next[index] = item
+			typedItems.value = next
+		}
+	}
+	const invalidate = () => {
+		collectionRevision++
+		stale.value = true
+	}
+	const mutationSucceeded = () => {
+		invalidate()
+		if (isComplexCollectionQuery(normalizedCurrentQuery())) totalCount.value = null
+	}
+
+	const getById = async (id: string | number, select: string = '*') => {
+		const response = await api.getById<TRow>(modelName, id, { key: primaryKey, select })
+		if (!response.success) throw response.error
+		return (response.data ?? null) as TRow | null
+	}
+
+	const create = async (payload: TInsert) => {
+		const response = await api.create<TRow>(modelName, payload as MutationPayload)
+		if (!response.success) throw response.error
+		const created = (response.data ?? null) as TRow | null
+		if (created === null || created === undefined) {
+			throw new Error(`Cannot create "${modelName}": Supabase returned no row.`)
+		}
+		mutationSucceeded()
+		const activeQuery = normalizedCurrentQuery()
+		if (!isComplexCollectionQuery(activeQuery)) {
+			addOrUpdate(created)
+			typedItems.value = sortCollection(typedItems.value as Record<string, any>[], activeQuery).slice(0, activeQuery.limit ?? 100) as TRow[]
+			if (totalCount.value != null) totalCount.value++
+		}
+		return created
+	}
+
+	const update = async (target: MutationTarget, payload: TUpdate) => {
+		const id = resolveMutationTarget(target, 'update')
+		const response = await api.update<TRow>(modelName, id, payload as MutationPayload, { key: primaryKey })
+		if (!response.success) throw response.error
+		const updated = (Array.isArray(response.data) ? response.data[0] : response.data) as TRow | null
+		if (updated) {
+			mutationSucceeded()
+			const activeQuery = normalizedCurrentQuery()
+			if (!isComplexCollectionQuery(activeQuery)) {
+				addOrUpdate(updated)
+				typedItems.value = sortCollection(typedItems.value as Record<string, any>[], activeQuery) as TRow[]
+			}
+		}
+		return updated ?? null
+	}
+
+	const remove = async (target: MutationTarget) => {
+		const id = resolveMutationTarget(target, 'remove')
+		const response = await api.remove(modelName, id, { key: primaryKey })
+		if (!response.success) throw response.error
+		const existed = typedItems.value.some(item => itemKey(item) === id)
+		mutationSucceeded()
+		typedItems.value = typedItems.value.filter(item => itemKey(item) !== id)
+		if (!isComplexCollectionQuery(normalizedCurrentQuery()) && existed && totalCount.value != null) totalCount.value--
+	}
+
+	const fetch = async (query: RowQuery = {}) => {
+		const requestId = ++fetchSequence
+		const startingRevision = collectionRevision
+		currentQuery = query
+		loading.value = true
+		error.value = null
+		const {
+			select = '*',
+			where,
+			limit = 100,
+			offset = 0,
+			search,
+			searchColumns,
+		} = query
+
+		const { orderBy, orderDirection, orderForeignTable } = normalizeOrder(
+			query.orderBy,
+			query.orderDirection,
+			query.orderForeignTable,
+			primaryKey,
+		)
+
+		let data: TRow[] = []
+		let count: number | null = null
+
+		try {
+			const response = await api.all<TRow>(modelName, {
+				select,
+				where,
+				orderBy,
+				orderDirection,
+				orderForeignTable,
+				limit,
+				offset,
+				search,
+				searchColumns,
+			})
+			if (!response.success) throw response.error
+
+			data = (response.data ?? []) as TRow[]
+			count = response.count ?? null
+
+		// Latest request wins: rapid search/filter changes must not let an older
+		// response overwrite the state already produced by a newer query.
+		if (requestId === fetchSequence && startingRevision === collectionRevision) {
+			typedItems.value = Array.isArray(data) ? data : []
+			totalCount.value = count ?? null
+			stale.value = false
+		}
+
+		return (Array.isArray(data) ? data : []) as TRow[]
+		} catch (fetchError) {
+			error.value = fetchError
+			stale.value = true
+			throw fetchError
+		} finally {
+			if (requestId === fetchSequence) loading.value = false
+		}
+	}
+
+	const refresh = (query: RowQuery = currentQuery) => fetch(query)
+
+	const subscribe = () => {
+		if (typeof window === 'undefined' || subscription) return
+		subscriptionOwnerId = supabaseUser.value?.id ?? null
+		subscription = supabase.channel(`public:${modelName}`)
+			.on('postgres_changes', { event: '*', schema: 'public', table: modelName }, (payload: any) => {
+				if (subscriptionOwnerId !== (supabaseUser.value?.id ?? null)) return
+				invalidate()
+				if (isComplexCollectionQuery(normalizedCurrentQuery())) return
+				if (payload.eventType === 'DELETE') typedItems.value = typedItems.value.filter(item => itemKey(item) !== payload.old?.[primaryKey])
+				else if (payload.new) {
+					addOrUpdate(payload.new as TRow)
+					typedItems.value = sortCollection(typedItems.value as Record<string, any>[], normalizedCurrentQuery()) as TRow[]
+				}
+			})
+			.subscribe()
+	}
+	const unsubscribe = async () => {
+		const active = subscription
+		subscription = null
+		subscriptionOwnerId = null
+		if (!active) return
+		if (typeof (supabase as any).removeChannel === 'function') await (supabase as any).removeChannel(active)
+		else await active.unsubscribe()
+	}
+	watch(() => supabaseUser.value?.id ?? null, () => {
+		void unsubscribe()
+		typedItems.value = []
+		totalCount.value = null
+		invalidate()
+	})
+
+	return {
+		items: typedItems,
+		totalCount,
+		loading,
+		error,
+		stale,
+		getById,
+		create,
+		update,
+		remove,
+		fetch,
+		refresh,
+		invalidate,
+		subscribe,
+		unsubscribe,
+	}
+}

package/runtime/query.ts

@@ -0,0 +1,126 @@
+import type { ListOptions, WhereClause, WhereOperator } from '../types/list'
+
+export type QueryBuilderLike = {
+	[key: string]: unknown
+	or: (expression: string) => QueryBuilderLike
+	order: (column: string, options: Record<string, unknown>) => QueryBuilderLike
+	range: (from: number, to: number) => QueryBuilderLike
+	eq: (column: string, value: unknown) => QueryBuilderLike
+	neq: (column: string, value: unknown) => QueryBuilderLike
+	gt: (column: string, value: unknown) => QueryBuilderLike
+	gte: (column: string, value: unknown) => QueryBuilderLike
+	lt: (column: string, value: unknown) => QueryBuilderLike
+	lte: (column: string, value: unknown) => QueryBuilderLike
+	ilike: (column: string, value: unknown) => QueryBuilderLike
+	in: (column: string, value: readonly unknown[]) => QueryBuilderLike
+}
+
+export function escapePostgrestSearchTerm(value: string) {
+	return value
+		.replace(/[\\%_]/g, match => `\\${match}`)
+		.replace(/[(),]/g, ' ')
+		.trim()
+}
+
+export function applySearch<T extends QueryBuilderLike>(query: T, options: ListOptions): T {
+	const search = options.search?.trim()
+	if (!search) return query
+
+	const columns = [...new Set((options.searchColumns ?? []).map(column => column.trim()).filter(Boolean))]
+	if (columns.length === 0) return query
+
+	const term = escapePostgrestSearchTerm(search)
+	if (!term) return query
+
+	const expression = columns.map(column => `${column}.ilike.%${term}%`).join(',')
+	return query.or(expression) as T
+}
+
+export function normalizePagination(options: Pick<ListOptions, 'limit' | 'offset'>) {
+	const limit = options.limit ?? 100
+	const offset = options.offset ?? 0
+
+	if (!Number.isSafeInteger(limit) || limit < 1) {
+		throw new RangeError('[nsdb] limit must be a positive safe integer.')
+	}
+	if (!Number.isSafeInteger(offset) || offset < 0) {
+		throw new RangeError('[nsdb] offset must be a non-negative safe integer.')
+	}
+
+	return { limit, offset }
+}
+
+export function applyListOptions<T extends QueryBuilderLike>(query: T, options: ListOptions): T {
+	const orderBy = options.orderBy
+	const orderDirection = options.orderDirection ?? 'asc'
+	const { limit, offset } = normalizePagination(options)
+	let finalQuery: QueryBuilderLike = query
+
+	if (orderBy && options.orderForeignTable) {
+		finalQuery = finalQuery.order(orderBy, {
+			ascending: orderDirection === 'asc',
+			referencedTable: options.orderForeignTable,
+		})
+	} else if (orderBy) {
+		finalQuery = finalQuery.order(orderBy, { ascending: orderDirection === 'asc' })
+	}
+
+	return finalQuery.range(offset, offset + limit - 1) as T
+}
+
+export function applySingleFilter<T extends QueryBuilderLike>(
+	query: T,
+	column: string,
+	filter: WhereOperator,
+): T {
+	switch (filter.op) {
+		case 'eq': return query.eq(column, filter.value) as T
+		case 'neq': return query.neq(column, filter.value) as T
+		case 'gt': return query.gt(column, filter.value) as T
+		case 'gte': return query.gte(column, filter.value) as T
+		case 'lt': return query.lt(column, filter.value) as T
+		case 'lte': return query.lte(column, filter.value) as T
+		case 'ilike': return query.ilike(column, filter.value) as T
+		case 'in': {
+			if (!Array.isArray(filter.value)) {
+				throw new TypeError(`[nsdb] The "in" filter for "${column}" requires an array value.`)
+			}
+			return query.in(column, filter.value) as T
+		}
+		default: throw new TypeError(`[nsdb] Unsupported filter operator for "${column}".`)
+	}
+}
+
+export function applyWhereFilters<T extends QueryBuilderLike>(query: T, where?: WhereClause): T {
+	if (!where || Object.keys(where).length === 0) return query
+
+	let finalQuery: QueryBuilderLike = query
+	for (const [column, rawValue] of Object.entries(where)) {
+		if (Array.isArray(rawValue)) {
+			const containsOperators = rawValue.some(
+				part => part != null && typeof part === 'object' && 'op' in part,
+			)
+			if (!containsOperators) {
+				finalQuery = finalQuery.in(column, rawValue)
+				continue
+			}
+
+			for (const part of rawValue) {
+				if (!part || typeof part !== 'object' || !('op' in part)) {
+					throw new TypeError(`[nsdb] Filter array for "${column}" cannot mix values and operators.`)
+				}
+				finalQuery = applySingleFilter(finalQuery, column, part as WhereOperator)
+			}
+			continue
+		}
+
+		if (rawValue && typeof rawValue === 'object' && 'op' in rawValue) {
+			finalQuery = applySingleFilter(finalQuery, column, rawValue as WhereOperator)
+			continue
+		}
+
+		finalQuery = finalQuery.eq(column, rawValue)
+	}
+
+	return finalQuery as T
+}