@lucashw68/nsdb 1.0.0-rc.2

package/scripts/generate-composables.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import path from 'path'
+import { parseArgs } from '../helpers/args.js'
+import { getOption, loadNsdbConfig } from '../helpers/config.js'
+import { exists, readText, writeText, ensureDir } from '../helpers/io.js'
+import {
+	createTsProject,
+	addSourceFile,
+	loadDatabaseAlias,
+	getPublicTablesType
+} from '../helpers/ts.js'
+import { modelHookName } from '../helpers/names.js'
+import { markGenerated } from '../helpers/generated.js'
+import { selectTableProperties } from '../helpers/tables.js'
+
+export async function main() {
+	const parsedArguments = parseArgs()
+	const currentWorkingDirectory = process.cwd()
+	const { config } = await loadNsdbConfig(currentWorkingDirectory, parsedArguments.get('config', ''))
+
+	const typesFilePath = path.resolve(
+		currentWorkingDirectory,
+		getOption(parsedArguments, config, 'types', 'paths.types')
+	)
+
+	const outputDirectory = path.resolve(
+		currentWorkingDirectory,
+		getOption(parsedArguments, config, 'outDir', 'paths.composables')
+	)
+
+	const outputFilePath = path.join(outputDirectory, 'useNsdbModels.ts')
+
+	const templateFilePath = path.resolve(
+		currentWorkingDirectory,
+		getOption(parsedArguments, config, 'template', 'templates.useNsdbModel')
+	)
+
+	if (!exists(typesFilePath)) {
+		console.error(`❌ Missing types file: ${typesFilePath}`)
+		process.exit(1)
+	}
+
+	if (!exists(templateFilePath)) {
+		console.error(`❌ Missing template: ${templateFilePath}`)
+		process.exit(1)
+	}
+
+	ensureDir(outputDirectory)
+
+	const project = createTsProject()
+	const sourceFile = addSourceFile(project, typesFilePath)
+	const databaseAlias = loadDatabaseAlias(sourceFile)
+
+	if (!databaseAlias) {
+		console.error('❌ Type alias "Database" not found')
+		process.exit(1)
+	}
+
+	const tablesType = getPublicTablesType(databaseAlias)
+	if (!tablesType) {
+		console.error('❌ Database["public"]["Tables"] not found')
+		process.exit(1)
+	}
+
+	const templateContent = readText(templateFilePath)
+
+	const importLines = []
+	const caseLines = []
+
+	const tableProperties = selectTableProperties(tablesType, config.tables)
+	for (const tableProperty of tableProperties) {
+		const tableName = tableProperty.getName()
+		const hookName = modelHookName(tableName) // ex: playlists -> usePlaylists
+
+		importLines.push(
+			`import { ${hookName} } from '~~/nsdb/models/${tableName}'`
+		)
+
+		caseLines.push(
+			`\t\tcase '${tableName}':\n\t\t\treturn ${hookName}(opts)`
+		)
+	}
+
+	const finalContent =
+		templateContent
+			.replace('// __IMPORTS__', importLines.join('\n'))
+			.replace('// __CASES__', caseLines.join('\n'))
+			.trimEnd() + '\n'
+
+	writeText(outputFilePath, markGenerated(finalContent))
+	console.log('✅ useNsdbModels:', path.relative(currentWorkingDirectory, outputFilePath))
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	main().catch((error) => {
+		console.error('❌ Unexpected error while generating composables.')
+		console.error(error)
+		process.exit(1)
+	})
+}

package/scripts/generate-enums.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import path from 'path'
+import { exists, ensureDir, writeText } from '../helpers/io.js'
+import { parseArgs } from '../helpers/args.js'
+import { getOption, loadNsdbConfig } from '../helpers/config.js'
+import {
+	createTsProject,
+	addSourceFile,
+	loadDatabaseAlias,
+	getPublicEnumsType
+} from '../helpers/ts.js'
+import { toPascal } from '../helpers/names.js'
+import { GENERATED_FILE_MARKER } from '../helpers/generated.js'
+
+/**
+ * Build the metadata needed to emit strongly typed enums derived from Database["public"]["Enums"].
+ */
+function extractEnumDescriptors(sourceFile, enumsType) {
+	const enumProperties = enumsType.getProperties()
+	return enumProperties.map((enumProperty) => {
+		const enumName = enumProperty.getName()
+		const pascalName = toPascal(enumName)
+		const enumType = enumProperty.getTypeAtLocation(sourceFile)
+		const unionMembers = enumType.isUnion() ? enumType.getUnionTypes() : []
+		const literalValues = unionMembers
+			.map((unionMember) => (
+				typeof unionMember.getLiteralValue === 'function'
+					? unionMember.getLiteralValue()
+					: undefined
+			))
+			.filter((literalValue) => typeof literalValue === 'string')
+
+		return { enumName, pascalName, literalValues }
+	})
+}
+
+function buildContent(databaseImportPath, descriptors) {
+	const headerLines = [
+		GENERATED_FILE_MARKER,
+		`// Source: Database["public"]["Enums"]`,
+		``,
+		`import type { Database } from '${databaseImportPath}'`,
+		``,
+	]
+
+	const enumBlocks = descriptors.flatMap((descriptor) => ([
+		`// Enum: ${descriptor.enumName}`,
+		`export type ${descriptor.pascalName} = Database['public']['Enums']['${descriptor.enumName}']`,
+		descriptor.literalValues.length
+			? `export const ${descriptor.pascalName}Values = ${JSON.stringify(descriptor.literalValues)} as const`
+			: `export const ${descriptor.pascalName}Values = [] as const`,
+		``,
+	]))
+
+	const enumMapLines = [
+		`export const Enums = {`,
+		...descriptors.map((descriptor) => `\t'${descriptor.enumName}': ${descriptor.pascalName}Values`),
+		`} as const`,
+		``,
+	]
+
+	return [...headerLines, ...enumBlocks, ...enumMapLines].join('\n')
+}
+
+export async function main() {
+	const parsedArguments = parseArgs()
+	const currentWorkingDirectory = process.cwd()
+	const { config } = await loadNsdbConfig(currentWorkingDirectory, parsedArguments.get('config', ''))
+	const typesFilePath = path.resolve(currentWorkingDirectory, getOption(parsedArguments, config, 'types', 'paths.types'))
+	const outputFilePath = path.resolve(currentWorkingDirectory, getOption(parsedArguments, config, 'out', 'paths.enums'))
+	const databaseImportPath = getOption(parsedArguments, config, 'db-import-path', 'imports.databaseTypes')
+
+	if (!exists(typesFilePath)) {
+		console.error(`❌ Missing types file: ${typesFilePath}`)
+		process.exit(1)
+	}
+
+	const project = createTsProject()
+	const sourceFile = addSourceFile(project, typesFilePath)
+	const databaseAlias = loadDatabaseAlias(sourceFile)
+	if (!databaseAlias) {
+		console.error(`❌ Type alias "Database" not found in ${typesFilePath}`)
+		process.exit(1)
+	}
+	const enumsType = getPublicEnumsType(databaseAlias)
+	if (!enumsType) {
+		console.warn('⚠️ Database["public"]["Enums"] not found — writing an empty file.')
+		ensureDir(path.dirname(outputFilePath))
+		writeText(outputFilePath, `${GENERATED_FILE_MARKER}\nexport {}\n`)
+		console.log(`✅ enums: ${path.relative(currentWorkingDirectory, outputFilePath)}`)
+		return
+	}
+
+	const descriptors = extractEnumDescriptors(sourceFile, enumsType)
+	const fileContent = buildContent(databaseImportPath, descriptors)
+	writeText(outputFilePath, fileContent)
+	console.log(`✅ enums: ${path.relative(currentWorkingDirectory, outputFilePath)} — ${descriptors.length} enum(s)`)
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	main().catch((error) => {
+		console.error('❌ Unexpected error while generating enums.')
+		console.error(error)
+		process.exit(1)
+	})
+}

package/scripts/generate-metadata.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import postgres from 'postgres'
+import { parseArgs } from '../helpers/args.js'
+import { getOption, loadNsdbConfig } from '../helpers/config.js'
+import { writeText } from '../helpers/io.js'
+
+function sameColumns(left, right) {
+	return left.length === right.length && left.every((column, index) => column === right[index])
+}
+
+export async function introspectDatabase({ dbUrl, schemaName = 'public' }) {
+	const sql = postgres(dbUrl, { max: 1, prepare: false })
+	try {
+		const columns = await sql`
+			select
+				cls.relname as table_name,
+				att.attname as column_name,
+				att.attnum as ordinal_position,
+				pg_catalog.format_type(att.atttypid, att.atttypmod) as data_type,
+				not att.attnotnull as nullable,
+				pg_get_expr(def.adbin, def.adrelid) as default_expression,
+				att.attidentity as identity_kind,
+				att.attgenerated as generated_kind,
+				typ.typtype = 'e' as is_enum,
+				typ.typname as database_type
+			from pg_catalog.pg_attribute att
+			join pg_catalog.pg_class cls on cls.oid = att.attrelid
+			join pg_catalog.pg_namespace ns on ns.oid = cls.relnamespace
+			join pg_catalog.pg_type typ on typ.oid = att.atttypid
+			left join pg_catalog.pg_attrdef def
+				on def.adrelid = att.attrelid and def.adnum = att.attnum
+			where ns.nspname = ${schemaName}
+				and cls.relkind in ('r', 'p')
+				and att.attnum > 0
+				and not att.attisdropped
+			order by cls.relname, att.attnum
+		`
+
+		const constraints = await sql`
+			select
+				con.conname as constraint_name,
+				con.contype as constraint_type,
+				local_table.relname as table_name,
+				foreign_table.relname as referenced_table,
+				array(
+					select local_att.attname
+					from unnest(con.conkey) with ordinality as key(attnum, position)
+					join pg_catalog.pg_attribute local_att
+						on local_att.attrelid = con.conrelid and local_att.attnum = key.attnum
+					order by key.position
+				) as columns,
+				case when con.confkey is null then array[]::text[] else array(
+					select foreign_att.attname
+					from unnest(con.confkey) with ordinality as key(attnum, position)
+					join pg_catalog.pg_attribute foreign_att
+						on foreign_att.attrelid = con.confrelid and foreign_att.attnum = key.attnum
+					order by key.position
+				) end as referenced_columns
+			from pg_catalog.pg_constraint con
+			join pg_catalog.pg_class local_table on local_table.oid = con.conrelid
+			join pg_catalog.pg_namespace ns on ns.oid = local_table.relnamespace
+			left join pg_catalog.pg_class foreign_table on foreign_table.oid = con.confrelid
+			where ns.nspname = ${schemaName} and con.contype in ('p', 'u', 'f')
+			order by local_table.relname, con.conname
+		`
+
+		const tables = {}
+		for (const column of columns) {
+			const table = tables[column.table_name] ??= {
+				primaryKey: [],
+				uniqueConstraints: [],
+				columns: {},
+				relationships: [],
+			}
+			const identity = column.identity_kind === 'a'
+				? 'always'
+				: column.identity_kind === 'd' ? 'byDefault' : false
+			const generated = column.generated_kind === 's'
+				? 'stored'
+				: column.generated_kind === 'v' ? 'virtual' : false
+			table.columns[column.column_name] = {
+				position: Number(column.ordinal_position),
+				dataType: column.data_type,
+				databaseType: column.database_type,
+				nullable: Boolean(column.nullable),
+				hasDefault: column.default_expression != null || Boolean(identity),
+				defaultExpression: column.default_expression,
+				identity,
+				generated,
+				enum: Boolean(column.is_enum),
+				primaryKey: false,
+				unique: false,
+				insertable: !generated && identity !== 'always',
+				updatable: !generated && identity !== 'always',
+			}
+		}
+
+		for (const constraint of constraints) {
+			const table = tables[constraint.table_name]
+			if (!table) continue
+			const constraintColumns = [...constraint.columns]
+			if (constraint.constraint_type === 'p') {
+				table.primaryKey = constraintColumns
+				for (const column of constraintColumns) {
+					table.columns[column].primaryKey = true
+					table.columns[column].updatable = false
+				}
+			}
+			if (constraint.constraint_type === 'p' || constraint.constraint_type === 'u') {
+				table.uniqueConstraints.push({ name: constraint.constraint_name, columns: constraintColumns })
+				if (constraintColumns.length === 1) table.columns[constraintColumns[0]].unique = true
+			}
+		}
+
+		for (const constraint of constraints.filter(item => item.constraint_type === 'f')) {
+			const table = tables[constraint.table_name]
+			if (!table) continue
+			const relationColumns = [...constraint.columns]
+			table.relationships.push({
+				foreignKeyName: constraint.constraint_name,
+				columns: relationColumns,
+				referencedRelation: constraint.referenced_table,
+				referencedColumns: [...constraint.referenced_columns],
+				isOneToOne: table.uniqueConstraints.some(unique => sameColumns(unique.columns, relationColumns)),
+			})
+		}
+
+		return { version: 1, schema: schemaName, tables }
+	} finally {
+		await sql.end()
+	}
+}
+
+export async function main() {
+	const parsedArguments = parseArgs()
+	const currentWorkingDirectory = process.cwd()
+	const { config } = await loadNsdbConfig(currentWorkingDirectory, parsedArguments.get('config', ''))
+	const dbUrl = getOption(parsedArguments, config, 'db-url', 'supabase.dbUrl', process.env.SUPABASE_DB_URL || '')
+	const schemaName = getOption(parsedArguments, config, 'schema', 'supabase.schema', 'public')
+	const outputPath = path.resolve(
+		currentWorkingDirectory,
+		getOption(parsedArguments, config, 'out', 'paths.metadata', 'nsdb/database.metadata.json'),
+	)
+
+	if (!dbUrl) {
+		console.warn(
+			'⚠️  Metadata introspection skipped: configure supabase.dbUrl or SUPABASE_DB_URL. ' +
+			'Generation will fall back to Supabase TypeScript types and cannot reliably infer SQL defaults, identity/generated columns, composite constraints, or inverse relations.'
+		)
+		return
+	}
+
+	const metadata = await introspectDatabase({ dbUrl, schemaName })
+	writeText(outputPath, `${JSON.stringify(metadata, null, 2)}\n`)
+	console.log(`✅ metadata: ${path.relative(currentWorkingDirectory, outputPath)}`)
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	main().catch((error) => {
+		console.error('❌ Failed to introspect PostgreSQL metadata.')
+		console.error(error)
+		process.exit(1)
+	})
+}

package/scripts/generate-models.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import path from 'path'
+import { parseArgs } from '../helpers/args.js'
+import { getOption, loadNsdbConfig } from '../helpers/config.js'
+import { exists, readText, writeText, ensureDir } from '../helpers/io.js'
+import {
+	createTsProject,
+	addSourceFile,
+	loadDatabaseAlias,
+	getPublicTablesType
+} from '../helpers/ts.js'
+import { toPascal, modelHookName, storeName, schemaName } from '../helpers/names.js'
+import { markGenerated, removeStaleGeneratedFiles } from '../helpers/generated.js'
+import { selectTableProperties } from '../helpers/tables.js'
+import { getColumnPolicies } from '../helpers/tables.js'
+import { getTableMetadata, loadDatabaseMetadata } from '../helpers/metadata.js'
+import { buildRelationCatalog } from '../helpers/relations.js'
+
+function asKeyUnion(keys) {
+	return keys.length ? keys.map(key => `'${key}'`).join(' | ') : 'never'
+}
+
+function relationRowsType(relations, config, tableColumnsByName) {
+	if (!relations.length) return '{}'
+	const lines = relations.map(relation => {
+		const targetColumns = tableColumnsByName.get(relation.referencedTable) ?? []
+		const targetPolicies = getColumnPolicies(config.tables, relation.referencedTable, targetColumns)
+		const omitted = targetColumns.filter(column => targetPolicies[column].serverOnly || !targetPolicies[column].selectable)
+		const rowType = `Omit<Tables<'${relation.referencedTable}'>, ${asKeyUnion(omitted)}>`
+		const valueType = relation.kind === 'hasMany' || relation.kind === 'manyToMany'
+			? `${rowType}[]`
+			: `${rowType}${relation.nullable ? ' | null' : ''}`
+		return `\t'${relation.alias}': ${valueType}`
+	})
+	return `{\n${lines.join('\n')}\n}`
+}
+
+function buildModelCode(tableProperty, templateContent, currentWorkingDirectory, config, databaseMetadata, locationNode, tableRelations, tableColumnsByName) {
+	const tableName = tableProperty.getName()
+	const pascalName = toPascal(tableName)
+	const rowTypeName = `${pascalName}Row`
+	const hookName = modelHookName(tableName)
+	const storeIdentifier = storeName(tableName)
+	const storeFileRelativePath = `stores/${storeIdentifier}.ts`
+	const storeAbsolutePath = path.resolve(currentWorkingDirectory, storeFileRelativePath)
+	const storeExists = exists(storeAbsolutePath)
+	const tableType = tableProperty.getTypeAtLocation(locationNode)
+	const rowType = tableType.getProperty('Row')?.getTypeAtLocation(locationNode)
+	const columnNames = rowType?.getProperties().map(property => property.getName()) ?? []
+	const policies = getColumnPolicies(config.tables, tableName, columnNames)
+	const tableMetadata = getTableMetadata(databaseMetadata, tableName)
+	const primaryKeyColumns = tableMetadata?.primaryKey ?? (columnNames.includes('id') ? ['id'] : [])
+	if (primaryKeyColumns.length !== 1) {
+		throw new Error(`[nsdb] ${tableName} requires exactly one primary key for generated CRUD; found ${primaryKeyColumns.length}.`)
+	}
+	const primaryKey = primaryKeyColumns[0]
+	const conventionalReadonly = ['id', 'created_at', 'updated_at', 'inserted_at']
+	const rowOmit = columnNames.filter(column => policies[column].serverOnly || !policies[column].selectable)
+	const insertOmit = columnNames.filter(column => {
+		if (policies[column].serverOnly || policies[column].editable === false) return true
+		if (tableMetadata) return !tableMetadata.columns[column]?.insertable
+		return conventionalReadonly.includes(column)
+	})
+	const updateOmit = columnNames.filter(column => {
+		if (policies[column].serverOnly || policies[column].editable === false) return true
+		if (tableMetadata) return !tableMetadata.columns[column]?.updatable
+		return conventionalReadonly.includes(column)
+	})
+
+	const code = templateContent
+		.replace(/__TABLE__/g, tableName)
+		.replace(/__PASCAL__/g, pascalName)
+		.replace(/__ROW__/g, rowTypeName)
+		.replace(/__HOOK__/g, hookName)
+		.replace(/__PRIMARY_KEY__/g, primaryKey)
+		.replace(/__ROW_OMIT__/g, asKeyUnion(rowOmit))
+		.replace(/__INSERT_OMIT__/g, asKeyUnion(insertOmit))
+		.replace(/__UPDATE_OMIT__/g, asKeyUnion(updateOmit))
+		.replace(/__RELATION_ROWS__/g, relationRowsType(tableRelations, config, tableColumnsByName))
+		.replace(/__STORE_IMPORT__/g, storeExists ? `import { ${storeIdentifier} } from '~~/stores/${storeIdentifier}'` : '')
+		.replace(/__STORE_CREATOR__/g, storeExists ? `(() => ${storeIdentifier}() as any)` : 'undefined')
+
+	return { code, hookName }
+}
+
+export async function main() {
+	const parsedArguments = parseArgs()
+	const currentWorkingDirectory = process.cwd()
+	const { config } = await loadNsdbConfig(currentWorkingDirectory, parsedArguments.get('config', ''))
+	const typesFilePath = path.resolve(currentWorkingDirectory, getOption(parsedArguments, config, 'types', 'paths.types'))
+	const outputDirectory = path.resolve(currentWorkingDirectory, getOption(parsedArguments, config, 'outDir', 'paths.models'))
+	const barrelFilePath = path.join(outputDirectory, 'index.ts')
+	const templateFilePath = path.resolve(
+		currentWorkingDirectory,
+		getOption(parsedArguments, config, 'template', 'templates.model')
+	)
+
+	if (!exists(typesFilePath)) {
+		console.error(`❌ Missing types file: ${typesFilePath}`)
+		process.exit(1)
+	}
+	if (!exists(templateFilePath)) {
+		console.error(`❌ Missing template: ${templateFilePath}`)
+		process.exit(1)
+	}
+	ensureDir(outputDirectory)
+
+	const project = createTsProject()
+	const sourceFile = addSourceFile(project, typesFilePath)
+	const databaseAlias = loadDatabaseAlias(sourceFile)
+	if (!databaseAlias) {
+		console.error('❌ Type alias "Database" not found')
+		process.exit(1)
+	}
+	const tablesType = getPublicTablesType(databaseAlias)
+	if (!tablesType) {
+		console.error('❌ Database["public"]["Tables"] not found')
+		process.exit(1)
+	}
+
+	const templateContent = readText(templateFilePath)
+	const databaseMetadata = loadDatabaseMetadata(currentWorkingDirectory, config)
+	const exportStatements = []
+	const generatedFileNames = []
+
+	const tableProperties = selectTableProperties(tablesType, config.tables)
+	const exposedTableNames = new Set(tableProperties.map(property => property.getName()))
+	const relationCatalog = buildRelationCatalog(databaseMetadata, exposedTableNames)
+	const tableColumnsByName = new Map(tableProperties.map(property => {
+		const tableType = property.getTypeAtLocation(databaseAlias)
+		const rowType = tableType.getProperty('Row')?.getTypeAtLocation(databaseAlias)
+		return [property.getName(), rowType?.getProperties().map(column => column.getName()) ?? []]
+	}))
+	for (const tableProperty of tableProperties) {
+		const tableName = tableProperty.getName()
+		const { code, hookName } = buildModelCode(
+			tableProperty,
+			templateContent,
+			currentWorkingDirectory,
+			config,
+			databaseMetadata,
+			databaseAlias,
+			relationCatalog[tableName] ?? [],
+			tableColumnsByName,
+		)
+		const modelFilePath = path.join(outputDirectory, `${tableName}.ts`)
+		writeText(modelFilePath, markGenerated(code))
+		console.log('✅ model:', path.relative(currentWorkingDirectory, modelFilePath))
+		exportStatements.push(`export * from './${tableName}' // ${hookName}`)
+		generatedFileNames.push(`${tableName}.ts`)
+	}
+
+	writeText(barrelFilePath, markGenerated(exportStatements.join('\n') + '\n'))
+	removeStaleGeneratedFiles(outputDirectory, ['index.ts', ...generatedFileNames])
+	console.log('✅ models barrel:', path.relative(currentWorkingDirectory, barrelFilePath))
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	main().catch((error) => {
+		console.error('❌ Unexpected error while generating models.')
+		console.error(error)
+		process.exit(1)
+	})
+}