@c15t/backend 0.0.1-rc.10

package/src/db/core/fields/id-generator.ts

@@ -0,0 +1,57 @@
+/**
+ * Custom ID generation system for C15T entities
+ *
+ * Provides prefixed, time-ordered, unique identifiers for all system entities.
+ * Each entity type has a specific prefix to make IDs self-descriptive about
+ * their origin and purpose.
+ */
+import baseX from 'base-x';
+
+/**
+ * Base-58 encoder for generating short, URL-friendly identifiers
+ * Uses a character set that avoids visually ambiguous characters.
+ */
+const b58 = baseX('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');
+
+/**
+ * Generates a unique ID with the specified prefix
+ *
+ * Creates time-ordered, prefixed, base58-encoded identifiers that:
+ * - Start with the provided prefix for clear identification
+ * - Embed a timestamp for chronological ordering
+ * - Include random data for uniqueness
+ *
+ * @param prefix - The prefix to use for the ID
+ * @returns A unique, prefixed identifier
+ *
+ * @example
+ * ```typescript
+ * const subjectId = generateId("sub"); // "sub_3hK4G..."
+ * const consentId = generateId("cns"); // "cns_5RtX9..."
+ * ```
+ */
+export function generateId(prefix: string): string {
+	const buf = crypto.getRandomValues(new Uint8Array(20));
+
+	/**
+	 * Epoch starts more recently to extend timestamp lifetime.
+	 * From 2023-11-14T22:13:20.000Z (1700000000000) to ~2159.
+	 */
+	const EPOCH_TIMESTAMP = 1_700_000_000_000;
+
+	const t = Date.now() - EPOCH_TIMESTAMP;
+
+	// Use 8 bytes for the timestamp (0..7) and shift accordingly:
+	const high = Math.floor(t / 0x100000000);
+	const low = t >>> 0;
+	buf[0] = (high >>> 24) & 255;
+	buf[1] = (high >>> 16) & 255;
+	buf[2] = (high >>> 8) & 255;
+	buf[3] = high & 255;
+	buf[4] = (low >>> 24) & 255;
+	buf[5] = (low >>> 16) & 255;
+	buf[6] = (low >>> 8) & 255;
+	buf[7] = low & 255;
+
+	return `${prefix}_${b58.encode(buf)}`;
+}

package/src/db/core/fields/index.ts

@@ -0,0 +1,56 @@
+// Export core types
+export type {
+	FieldType,
+	Field,
+	FieldConfig,
+	Primitive,
+	JsonValue,
+} from './field-types';
+
+// Export field options
+export type {
+	NumberFieldOptions,
+	StringFieldOptions,
+	JsonFieldOptions,
+	TimezoneFieldOptions,
+	DateFieldOptions,
+} from './field-factory';
+
+// Export factory functions
+export {
+	createField,
+	stringField,
+	numberField,
+	booleanField,
+	dateField,
+	jsonField,
+	stringArrayField,
+	numberArrayField,
+	timezoneField,
+	COMMON_TIMEZONES,
+} from './field-factory';
+
+// Export Zod utilities
+export {
+	validateField,
+	createFieldValueSchema,
+} from './zod-fields';
+
+// Export field inference utilities
+export type {
+	InferFieldOutput,
+	InferFieldInput,
+	InferFieldsOutput,
+	InferFieldsInput,
+	TransformOutputFn,
+} from './field-inference';
+
+// Export SuperJSON utilities
+export {
+	getDatabaseType,
+	transformForDb,
+	parseFromDb,
+} from './superjson-utils';
+
+// Export ID generator
+export { generateId } from './id-generator';

package/src/db/core/fields/superjson-utils.ts

@@ -0,0 +1,155 @@
+import superjson from 'superjson';
+
+/**
+ * Database type enumeration
+ * Used to identify the current database type for data handling decisions
+ */
+export type DatabaseType = 'sqlite' | 'postgresql' | 'mysql' | 'unknown';
+
+/**
+ * Get the current database type from a provider string
+ *
+ * @param provider - The database provider string
+ * @returns The normalized database type
+ */
+export function normalizeDatabaseType(provider?: string): DatabaseType {
+	if (!provider) {
+		return 'unknown';
+	}
+
+	// Normalize provider names
+	switch (provider.toLowerCase()) {
+		case 'pg':
+		case 'postgres':
+		case 'postgresql':
+			return 'postgresql';
+		case 'mysql':
+		case 'mariadb':
+			return 'mysql';
+		case 'sqlite':
+		case 'sqlite3':
+			return 'sqlite';
+		default:
+			return 'unknown';
+	}
+}
+
+// Global database type setting that can be configured at startup
+const currentDatabaseType: DatabaseType = 'unknown';
+
+/**
+ * Get the current database type
+ *
+ * @returns The current database type
+ */
+export function getDatabaseType(): DatabaseType {
+	return currentDatabaseType;
+}
+
+/**
+ * Apply database-specific transformations for JSON data
+ *
+ * @param value - The value to transform
+ * @param dbType - The database type (defaults to current global setting)
+ * @returns Transformed value appropriate for the database
+ */
+export function transformForDb<T>(
+	value: T,
+	dbType: DatabaseType = currentDatabaseType
+): T | string {
+	// For SQLite, always use SuperJSON
+	if (dbType === 'sqlite') {
+		return superjson.stringify(value);
+	}
+
+	// For MySQL, use SuperJSON for complex types
+	if (dbType === 'mysql') {
+		// Check if value contains complex types
+		const containsComplexTypes = containsComplexJsTypes(value);
+
+		if (containsComplexTypes) {
+			return superjson.stringify(value);
+		}
+	}
+
+	// For PostgreSQL, use native JSON
+	return value;
+}
+
+/**
+ * Parse a value from the database using the global database type.
+ *
+ * @param value - The value from the database
+ * @returns Parsed value
+ */
+export function parseFromDb(value: unknown) {
+	// If the value is a string and might be SuperJSON format
+	if (typeof value === 'string' && isSuperJsonString(value)) {
+		try {
+			return superjson.parse(value);
+		} catch {
+			// If parsing fails, return the original value
+			return value;
+		}
+	}
+
+	return value;
+}
+
+/**
+ * Check if a string looks like it might be in SuperJSON format
+ *
+ * @param str - The string to check
+ * @returns Whether the string appears to be SuperJSON
+ */
+function isSuperJsonString(str: string): boolean {
+	try {
+		const parsed = JSON.parse(str);
+		// SuperJSON format has 'json' and 'meta' properties
+		return (
+			typeof parsed === 'object' &&
+			parsed !== null &&
+			'json' in parsed &&
+			'meta' in parsed
+		);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if a value contains complex JavaScript types
+ * that might not be properly handled by standard JSON
+ *
+ * @param value - The value to check
+ * @returns Whether the value contains complex types
+ */
+function containsComplexJsTypes(value: unknown): boolean {
+	if (value === null || value === undefined) {
+		return false;
+	}
+
+	// Check for Date, Map, Set, BigInt, or other non-standard JSON types
+	if (
+		value instanceof Date ||
+		value instanceof Map ||
+		value instanceof Set ||
+		typeof value === 'bigint' ||
+		ArrayBuffer.isView(value)
+	) {
+		return true;
+	}
+
+	// Recursively check objects and arrays
+	if (Array.isArray(value)) {
+		return value.some((item) => containsComplexJsTypes(item));
+	}
+
+	if (typeof value === 'object') {
+		return Object.values(value as Record<string, unknown>).some((item) =>
+			containsComplexJsTypes(item)
+		);
+	}
+
+	return false;
+}

package/src/db/core/fields/zod-fields.ts

@@ -0,0 +1,269 @@
+import { z } from 'zod';
+import type {
+	Field,
+	FieldType,
+	InferValueType,
+	JsonValue,
+} from './field-types';
+
+/**
+ * Base Zod schema for field configuration options
+ */
+const fieldConfigSchema = z.object({
+	required: z.boolean().default(true),
+	returned: z.boolean().default(true),
+	input: z.boolean().default(true),
+	defaultValue: z.union([z.any(), z.function().returns(z.any())]).optional(),
+	transform: z
+		.object({
+			input: z
+				.function()
+				.args(z.any())
+				.returns(z.union([z.any(), z.promise(z.any())]))
+				.optional(),
+			output: z
+				.function()
+				.args(z.any())
+				.returns(z.union([z.any(), z.promise(z.any())]))
+				.optional(),
+		})
+		.optional(),
+	validator: z
+		.function()
+		.args(z.any())
+		.returns(z.union([z.string(), z.null()]))
+		.optional(),
+	unique: z.boolean().optional(),
+	indexed: z.boolean().optional(),
+	sortable: z.boolean().default(true),
+	fieldName: z.string().optional(),
+	bigint: z.boolean().default(false),
+});
+
+/**
+ * Zod schema for string field configuration
+ */
+export const stringFieldSchema = fieldConfigSchema.extend({
+	type: z.literal('string'),
+	minLength: z.number().optional(),
+	maxLength: z.number().optional(),
+	pattern: z.string().optional(),
+});
+
+/**
+ * Zod schema for number field configuration
+ */
+export const numberFieldSchema = fieldConfigSchema.extend({
+	type: z.literal('number'),
+	min: z.number().optional(),
+	max: z.number().optional(),
+});
+
+/**
+ * Zod schema for boolean field configuration
+ */
+export const booleanFieldSchema = fieldConfigSchema.extend({
+	type: z.literal('boolean'),
+});
+
+/**
+ * Zod schema for date field configuration
+ */
+export const dateFieldSchema = fieldConfigSchema.extend({
+	type: z.literal('date'),
+	minDate: z.date().optional(),
+	maxDate: z.date().optional(),
+	dateOnly: z.boolean().default(false),
+	format: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Zod schema for timezone field configuration
+ */
+export const timezoneFieldSchema = fieldConfigSchema.extend({
+	type: z.literal('timezone'),
+	validateTimezone: z.boolean().default(true),
+	suggestedValues: z.array(z.string()).optional(),
+	restrictToSuggestedValues: z.boolean().default(false),
+});
+
+/**
+ * Zod schema for JSON field configuration
+ */
+export const jsonFieldSchema = fieldConfigSchema.extend({
+	type: z.literal('json'),
+	validateJson: z.boolean().default(true),
+});
+
+/**
+ * Zod schema for string array field configuration
+ */
+export const stringArrayFieldSchema = fieldConfigSchema.extend({
+	type: z.literal('string[]'),
+});
+
+/**
+ * Zod schema for number array field configuration
+ */
+export const numberArrayFieldSchema = fieldConfigSchema.extend({
+	type: z.literal('number[]'),
+});
+
+/**
+ * Union type of all field schemas
+ */
+export const fieldSchema = z.discriminatedUnion('type', [
+	stringFieldSchema,
+	numberFieldSchema,
+	booleanFieldSchema,
+	dateFieldSchema,
+	timezoneFieldSchema,
+	jsonFieldSchema,
+	stringArrayFieldSchema,
+	numberArrayFieldSchema,
+]);
+
+/**
+ * Type for a validated field configuration
+ */
+export type ValidatedField<TFieldType extends FieldType> = z.infer<
+	typeof fieldSchema
+> & {
+	type: TFieldType;
+};
+
+/**
+ * Creates a Zod schema for a field's value based on its type
+ */
+export function createFieldValueSchema<TFieldType extends FieldType>(
+	field: ValidatedField<TFieldType>
+): z.ZodType<InferValueType<TFieldType>> {
+	type ValueType = InferValueType<TFieldType>;
+
+	const baseSchema = (() => {
+		switch (field.type) {
+			case 'string': {
+				let schema = z.string();
+				if ('minLength' in field && field.minLength !== undefined) {
+					schema = schema.min(field.minLength);
+				}
+				if ('maxLength' in field && field.maxLength !== undefined) {
+					schema = schema.max(field.maxLength);
+				}
+				if ('pattern' in field && field.pattern) {
+					schema = schema.regex(new RegExp(field.pattern));
+				}
+				return schema;
+			}
+
+			case 'number': {
+				let schema = z.number();
+				if ('min' in field && field.min !== undefined) {
+					schema = schema.min(field.min);
+				}
+				if ('max' in field && field.max !== undefined) {
+					schema = schema.max(field.max);
+				}
+				return schema;
+			}
+
+			case 'boolean':
+				return z.boolean();
+
+			case 'date': {
+				let schema = z.date();
+				if ('minDate' in field && field.minDate) {
+					schema = schema.min(field.minDate);
+				}
+				if ('maxDate' in field && field.maxDate) {
+					schema = schema.max(field.maxDate);
+				}
+				return schema;
+			}
+
+			case 'timezone': {
+				let schema: z.ZodType<string> = z.string();
+				if ('validateTimezone' in field && field.validateTimezone) {
+					schema = schema.superRefine((val, ctx) => {
+						try {
+							Intl.DateTimeFormat(undefined, { timeZone: val });
+						} catch {
+							ctx.addIssue({
+								code: z.ZodIssueCode.custom,
+								message: 'Invalid timezone',
+							});
+						}
+					});
+				}
+				if (
+					'restrictToSuggestedValues' in field &&
+					field.restrictToSuggestedValues &&
+					'suggestedValues' in field &&
+					field.suggestedValues
+				) {
+					const suggestedValues = field.suggestedValues;
+					schema = schema.superRefine((val, ctx) => {
+						if (!suggestedValues.includes(val)) {
+							ctx.addIssue({
+								code: z.ZodIssueCode.custom,
+								message: 'Timezone not in allowed values',
+							});
+						}
+					});
+				}
+				return schema;
+			}
+
+			case 'json': {
+				let schema: z.ZodType<JsonValue> = z.any();
+				if ('validateJson' in field && field.validateJson) {
+					schema = schema.superRefine((val, ctx) => {
+						try {
+							JSON.stringify(val);
+						} catch {
+							ctx.addIssue({
+								code: z.ZodIssueCode.custom,
+								message: 'Invalid JSON',
+							});
+						}
+					});
+				}
+				return schema;
+			}
+
+			case 'string[]':
+				return z.array(z.string());
+
+			case 'number[]':
+				return z.array(z.number());
+
+			default:
+				throw new Error(`Unsupported field type: ${field.type}`);
+		}
+	})() as z.ZodType<ValueType>;
+
+	// Apply custom validation if provided
+	if (field.validator) {
+		const validator = field.validator;
+		return baseSchema.superRefine((val, ctx) => {
+			const result = validator(val);
+			if (result !== null) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: result,
+				});
+			}
+		}) as z.ZodType<ValueType>;
+	}
+
+	return baseSchema;
+}
+
+/**
+ * Validates a field configuration against its schema
+ */
+export function validateField<TFieldType extends FieldType>(
+	field: Field<TFieldType>
+): ValidatedField<TFieldType> {
+	return fieldSchema.parse(field) as ValidatedField<TFieldType>;
+}

package/src/db/core/get-schema.ts

@@ -0,0 +1,102 @@
+import type { Field } from '~/db/core/fields';
+import type { EntityName } from '~/db/core/types';
+import type { C15TOptions } from '~/types';
+import { getConsentTables } from '../index';
+
+/**
+ * A schema entry representing a processed entity definition.
+ * Contains fields and creation/sorting order information.
+ *
+ * @internal
+ * @interface SchemaEntry
+ * @property {Record<string, Field>} fields - Map of field names to their definitions
+ * @property {number} order - Order priority for entity creation (lower numbers first)
+ */
+interface SchemaEntry {
+	fields: Record<string, Field>;
+	order: number;
+}
+
+/**
+ * Processes entity definitions from configuration into a standardized schema format.
+ *
+ * This function takes raw configuration and builds a complete schema with properly
+ * structured field definitions, handling field name mapping, references between
+ * entities, and merging duplicate entity definitions.
+ *
+ * @param {C15TOptions} config - The application configuration
+ * @returns {Record<string, SchemaEntry>} A map of entity names to their schema entries
+ *
+ * @example
+ * ```typescript
+ * const schema = getSchema(config);
+ *
+ * // Access subject entity definition
+ * const subjectFields = schema.subject.fields;
+ * ```
+ */
+export function getSchema(config: C15TOptions) {
+	const entities = getConsentTables(config);
+	const schema: Record<string, SchemaEntry> = {};
+
+	for (const [key, entity] of Object.entries(entities)) {
+		if (!entity) {
+			continue; // Skip if entity is undefined
+		}
+
+		const fields = entity.fields || {}; // Default to empty object if fields is undefined
+		const processedFields: Record<string, Field> = {};
+
+		// Process each field
+		for (const [fieldKey, field] of Object.entries(fields)) {
+			if (!field) {
+				continue; // Skip if field is undefined
+			}
+
+			const fieldName = field.fieldName || fieldKey;
+			// Cast field to Field to ensure it has the right type
+			const typedField = field as Field;
+			processedFields[fieldName] = typedField;
+
+			// Handle references - first check if the field has a references property
+			if (typedField && 'references' in typedField && typedField.references) {
+				const entityName = typedField.references.model as EntityName;
+				const referencedEntity = entities[entityName];
+				if (referencedEntity) {
+					// Create a new object for references to avoid modifying the original
+					processedFields[fieldName] = {
+						...typedField,
+						references: {
+							model: referencedEntity.entityName,
+							entity: referencedEntity.entityName,
+							field: typedField.references.field,
+							onDelete: typedField.references.onDelete,
+						},
+					};
+				}
+			}
+		}
+
+		// Update or create schema entry
+		const entityName = entity.entityName || key;
+		if (entityName in schema) {
+			const existingEntry = schema[entityName];
+
+			schema[entityName] = {
+				...existingEntry,
+				order: existingEntry?.order ?? Number.POSITIVE_INFINITY,
+				fields: {
+					...existingEntry?.fields,
+					...processedFields,
+				},
+			};
+		} else {
+			schema[entityName] = {
+				fields: processedFields,
+				order: entity.order ?? Number.POSITIVE_INFINITY,
+			};
+		}
+	}
+
+	return schema;
+}

package/src/db/core/types.ts

@@ -0,0 +1,52 @@
+import type { C15TDBSchema } from '../schema/definition';
+import type { Field } from './fields';
+
+/**
+ * Plugin-provided schema type with proper typing.
+ * Defines the structure of schemas that plugins can provide to extend the system.
+ *
+ * @template TEntityKey - The entity key in the schema
+ */
+export type PluginSchema = Record<
+	string,
+	{
+		fields: Record<string, Field>;
+		entityName?: string;
+	}
+>;
+
+/**
+ * Maps entity keys to their corresponding data structures.
+ * Provides type access to all entities defined in the database schema.
+ *
+ * @template TKey - Entity key in the database schema
+ */
+export type EntityTypeMap = {
+	[TKey in keyof C15TDBSchema]: C15TDBSchema[TKey];
+};
+
+/**
+ * All valid entity names in the database schema.
+ * This type represents the keys of all entities that can be used in queries.
+ */
+export type EntityName = keyof C15TDBSchema;
+
+/**
+ * Input type for entity operations, allowing partial fields and additional properties.
+ * Used when creating or updating entity records.
+ *
+ * @template TEntity - The entity type being operated on
+ */
+export type EntityInput<TEntity extends EntityName> = Partial<
+	EntityTypeMap[TEntity]
+> &
+	Record<string, unknown>;
+
+/**
+ * Output type for entity operations returned from the database.
+ * Represents the full structure of an entity as returned from queries.
+ *
+ * @template TEntity - The entity type being returned
+ */
+export type EntityOutput<TEntity extends EntityName> = EntityTypeMap[TEntity] &
+	Record<string, unknown>;