@c15t/backend 0.0.1-rc.10

package/src/db/schema/types.ts

@@ -0,0 +1,154 @@
+/**
+ * Database Schema Type Definitions
+ *
+ * This module contains base type definitions for database schema configuration.
+ * These types define the common structure of entity configurations used throughout
+ * the c15t consent management system.
+ */
+import type { Field } from '~/db/core/fields';
+
+import type { AuditLogEntityConfig } from './audit-log/types';
+import type { ConsentGeoLocationEntityConfig } from './consent-geo-location/types';
+import type { ConsentPolicyEntityConfig } from './consent-policy/types';
+import type { ConsentPurposeJunctionEntityConfig } from './consent-purpose-junction/types';
+import type { ConsentPurposeEntityConfig } from './consent-purpose/types';
+import type { ConsentRecordEntityConfig } from './consent-record/types';
+import type { ConsentWithdrawalEntityConfig } from './consent-withdrawal/types';
+import type { ConsentEntityConfig } from './consent/types';
+import type { DomainEntityConfig } from './domain/types';
+import type { GeoLocationEntityConfig } from './geo-location/types';
+import type { SubjectEntityConfig } from './subject/types';
+
+/**
+ * Base entity configuration shared by all entities
+ * Provides common configuration options for database entities
+ */
+export interface BaseEntityConfig {
+	/**
+	 * Custom model name for the entity table
+	 */
+	entityName?: string;
+
+	/**
+	 * The ID prefix for the entity table
+	 * Used to generate unique prefixed IDs
+	 */
+	entityPrefix?: string;
+
+	/**
+	 * Custom field names for the entity table
+	 */
+	fields?: Record<string, string>;
+
+	/**
+	 * Additional fields for the entity table
+	 */
+	additionalFields?: Record<string, Field>;
+}
+
+/**
+ * Entity configuration with standard timestamps
+ * Extends base configuration with created/updated timestamp fields
+ */
+export interface TimestampedEntityConfig extends BaseEntityConfig {
+	fields?: Record<string, string> & {
+		createdAt?: string;
+		updatedAt?: string;
+	};
+}
+
+/**
+ * Entity configuration for entities with active status
+ * Extends timestamped configuration with isActive field
+ */
+export interface ActiveEntityConfig extends TimestampedEntityConfig {
+	fields?: Record<string, string> & {
+		createdAt?: string;
+		updatedAt?: string;
+		isActive?: string;
+	};
+}
+
+/**
+ * Database tables configuration
+ * Contains all entity table configurations in one unified object
+ */
+export interface TablesConfig {
+	/**
+	 * Subject entity configuration
+	 * @default entityName: "subject", entityPrefix: "sub"
+	 */
+	subject?: SubjectEntityConfig;
+
+	/**
+	 * Domain configuration
+	 * @default entityName: "domain", entityPrefix: "dom"
+	 */
+	domain?: DomainEntityConfig;
+
+	/**
+	 * Geo location configuration
+	 * @default entityName: "geoLocation", entityPrefix: "geo"
+	 */
+	geoLocation?: GeoLocationEntityConfig;
+
+	/**
+	 * ConsentPurpose entity configuration
+	 * @default entityName: "consentPurpose", entityPrefix: "pur"
+	 */
+	consentPurpose?: ConsentPurposeEntityConfig;
+
+	/**
+	 * Consent policy configuration
+	 * @default entityName: "consentPolicy", entityPrefix: "pol"
+	 */
+	consentPolicy?: ConsentPolicyEntityConfig;
+
+	/**
+	 * Consent configuration
+	 * @default entityName: "consent", entityPrefix: "cns"
+	 */
+	consent?: ConsentEntityConfig;
+
+	/**
+	 * ConsentPurpose junction configuration
+	 * @default entityName: "consentPurposeJunction", entityPrefix: "pjx"
+	 */
+	consentPurposeJunction?: ConsentPurposeJunctionEntityConfig;
+
+	/**
+	 * Consent geo location configuration
+	 * @default entityName: "consentGeoLocation", entityPrefix: "cgl"
+	 */
+	consentGeoLocation?: ConsentGeoLocationEntityConfig;
+
+	/**
+	 * Record entity configuration
+	 * @default entityName: "record", entityPrefix: "rec"
+	 */
+	record?: ConsentRecordEntityConfig;
+
+	/**
+	 * Withdrawal configuration
+	 * @default entityName: "consentWithdrawal", entityPrefix: "wdr"
+	 */
+	consentWithdrawal?: ConsentWithdrawalEntityConfig;
+
+	/**
+	 * Audit log configuration
+	 * @default entityName: "auditLog", entityPrefix: "log"
+	 */
+	auditLog?: AuditLogEntityConfig;
+}
+
+export type { AuditLogEntityConfig } from './audit-log/types';
+export type { ConsentEntityConfig } from './consent/types';
+export type { ConsentGeoLocationEntityConfig } from './consent-geo-location/types';
+export type { ConsentPolicyEntityConfig } from './consent-policy/types';
+export type { ConsentPurposeEntityConfig } from './consent-purpose/types';
+export type { ConsentPurposeJunctionEntityConfig } from './consent-purpose-junction/types';
+export type { ConsentRecordEntityConfig } from './consent-record/types';
+export type { ConsentWithdrawalEntityConfig } from './consent-withdrawal/types';
+export type { DomainEntityConfig } from './domain/types';
+export type { GeoLocationEntityConfig } from './geo-location/types';
+export type { SubjectEntityConfig } from './subject/types';

package/src/db/utils/adapter-factory.ts

@@ -0,0 +1,64 @@
+import { getConsentTables } from '~/db';
+import { kyselyAdapter } from '~/db/adapters/kysely-adapter';
+import { createKyselyAdapter } from '~/db/adapters/kysely-adapter/dialect';
+import { memoryAdapter } from '~/db/adapters/memory-adapter';
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { C15TOptions } from '~/types';
+import { createLogger } from '~/utils/logger';
+
+/**
+ * Creates and configures the appropriate database adapter based on C15T options
+ *
+ * This function handles several scenarios:
+ * 1. No database configuration - creates an in-memory adapter (development only)
+ * 2. Custom database function - uses the provided function to create an adapter
+ * 3. Standard database config - creates a Kysely adapter with the specified database
+ *
+ * @param options - The C15T configuration options
+ * @returns A configured database adapter instance
+ * @throws {C15TError} If the database adapter initialization fails
+ *
+ * @example
+ * ```typescript
+ * const adapter = await getAdapter(config);
+ * const subjects = await adapter.findMany('subject', { where: { active: true } });
+ * ```
+ */
+export async function getAdapter(options: C15TOptions) {
+	const logger = createLogger();
+
+	// If no database is configured, use an in-memory adapter for development
+	if (!options.database) {
+		const tables = getConsentTables(options);
+		const memoryDB = Object.keys(tables).reduce<Record<string, []>>(
+			(acc, key) => {
+				acc[key] = [];
+				return acc;
+			},
+			{}
+		);
+
+		logger.warn(
+			'No database configuration provided. Using memory adapter in development'
+		);
+		return memoryAdapter(memoryDB)(options);
+	}
+
+	// If a custom database function is provided, use it directly
+	if (typeof options.database === 'function') {
+		return options.database(options);
+	}
+
+	// Otherwise, create a Kysely adapter
+	const { kysely, databaseType } = await createKyselyAdapter(options);
+	if (!kysely) {
+		throw new C15TError('Failed to initialize database adapter', {
+			code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+			status: 500,
+		});
+	}
+
+	return kyselyAdapter(kysely, {
+		type: databaseType || 'sqlite',
+	})(options);
+}

package/src/db/utils/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Database Utilities Module
+ *
+ * This module provides various utility functions for database operations,
+ * including adapter creation and data conversion between application and database formats.
+ *
+ * @module db/utils
+ */
+
+export { getAdapter } from './adapter-factory';

package/src/db/utils.ts

@@ -0,0 +1,42 @@
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { C15TOptions } from '~/types';
+import { logger } from '../utils';
+import { kyselyAdapter } from './adapters/kysely-adapter';
+import { createKyselyAdapter } from './adapters/kysely-adapter/dialect';
+import { memoryAdapter } from './adapters/memory-adapter';
+import type { Adapter } from './adapters/types';
+import { getConsentTables } from './index';
+
+export async function getAdapter(options: C15TOptions): Promise<Adapter> {
+	if (!options.database) {
+		const tables = getConsentTables(options);
+		const memoryDB = Object.keys(tables).reduce<Record<string, unknown[]>>(
+			(acc, key) => {
+				acc[key] = [];
+				return acc;
+			},
+			{}
+		);
+		logger.warn(
+			'No database configuration provided. Using memory adapter in development'
+		);
+		return memoryAdapter(memoryDB as Record<string, Record<string, unknown>[]>)(
+			options
+		);
+	}
+
+	if (typeof options.database === 'function') {
+		return options.database(options);
+	}
+
+	const { kysely, databaseType } = await createKyselyAdapter(options);
+	if (!kysely) {
+		throw new C15TError('Failed to initialize database adapter', {
+			code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+			status: 500,
+		});
+	}
+	return kyselyAdapter(kysely, {
+		type: databaseType || 'sqlite',
+	})(options);
+}

package/src/docs/ADVANCED_JSON_HANDLING.md

@@ -0,0 +1,99 @@
+# Advanced JSON and Date Handling in C15T
+
+C15T provides intelligent, database-specific handling for JSON data and date/time values to ensure maximum compatibility and performance across different database systems. This document explains how data is stored and accessed in different database environments.
+
+## SuperJSON Integration
+
+C15T uses [SuperJSON](https://github.com/blitz-js/superjson) to enhance JSON serialization for complex JavaScript types that aren't natively supported by JSON, such as:
+
+- `Date` objects with timezone information
+- JavaScript `Map` and `Set` objects
+- `BigInt` values
+- `undefined` values
+- Custom class instances
+- And more
+
+## Database-Specific Behavior
+
+### PostgreSQL
+
+PostgreSQL has excellent native support for both JSON and timestamps with timezone:
+
+- **JSON fields**: Uses native JSONB type for most JSON data, with SuperJSON only applied when needed for complex JS types
+- **Date fields**: Uses native TIMESTAMPTZ which properly preserves timezone information
+- **Benefits**: Offers high performance and the ability to perform JSON path queries directly in the database
+
+### MySQL
+
+MySQL has native JSON support but more limited date/timezone handling:
+
+- **JSON fields**: Uses native JSON type with SuperJSON selectively applied for complex types
+- **Date fields**: Uses consistent timezone handling to ensure predictable behavior
+- **Benefits**: Provides good balance between native database features and JavaScript type support
+
+### SQLite
+
+SQLite has no native JSON or timezone-aware date types:
+
+- **JSON fields**: Always uses SuperJSON format stored as TEXT to preserve all JavaScript types
+- **Date fields**: Uses special handling to maintain timezone information
+- **Benefits**: Maintains complete JavaScript data structures even with SQLite's simpler type system
+
+## Implications for Your Application
+
+### Accessing Data Outside C15T
+
+When accessing data stored by C15T from outside the library (e.g., direct database queries), be aware:
+
+- **PostgreSQL data**: Most fields can be accessed directly without special handling
+- **MySQL data**: Complex values might be in SuperJSON format (look for `{"json":..., "meta":...}` structure)
+- **SQLite data**: All JSON and date fields will be in SuperJSON format and require parsing
+
+To parse SuperJSON data outside of C15T:
+
+```javascript
+// If using SuperJSON
+const data = superjson.parse(valueFromDatabase);
+
+// Without SuperJSON, you can manually extract the data
+const parsed = JSON.parse(valueFromDatabase);
+const actualData = parsed.json; // The actual data is in the 'json' property
+```
+
+### Best Practices
+
+1. **Use C15T's API** when possible to abstract away database differences
+2. **Document data format** if you expect other systems to access the database directly
+3. **Consider database requirements** when designing systems that need to use multiple database types
+4. **Test across databases** if your application needs to support multiple database types
+
+## Configuration
+
+The database-specific handling is applied automatically based on your database configuration when you initialize C15T.
+
+If needed, you can manually set the database type:
+
+```typescript
+import { setDatabaseType } from '@c15t/backend/db/core/fields/superjson-utils';
+
+// Must be called before using any field operations
+setDatabaseType('sqlite'); // or 'postgresql', 'mysql'
+```
+
+## Extending SuperJSON
+
+If you need to support additional custom types with SuperJSON, you can register them:
+
+```typescript
+import superjson from 'superjson';
+
+// Register a custom type
+superjson.registerCustom<MyCustomType, string>(
+  // isMyType check
+  (v) => v instanceof MyCustomType,
+  // serialize
+  (v) => v.toString(),
+  // deserialize
+  (v) => new MyCustomType(v)
+);
+``` 

package/src/docs/neverthrow.md

@@ -0,0 +1,171 @@
+# Using neverthrow in c15t
+
+## Overview
+
+The c15t library now supports a functional approach to error handling using the [neverthrow](https://github.com/supermacro/neverthrow) library. This approach provides several benefits:
+
+- More explicit error handling with the `Result` type
+- Better type safety and compile-time checks for error cases
+- Ability to chain operations with proper error propagation
+- No need for try/catch blocks or exception handling
+- Clearer and more predictable code flow
+
+This document explains how to use the neverthrow `Result` pattern with c15t.
+
+## Basic Concepts
+
+The core concept of neverthrow is the `Result` type, which represents either:
+
+- A successful operation (`Ok` variant) containing a value, or
+- A failed operation (`Err` variant) containing an error
+
+Instead of throwing exceptions, functions return a `Result` that must be handled explicitly.
+
+### Result vs Traditional Error Handling
+
+Traditional approach:
+```typescript
+try {
+  const context = await init(options);
+  // Use context...
+} catch (error) {
+  // Handle errors...
+}
+```
+
+neverthrow approach:
+```typescript
+const contextResult = await init(options);
+contextResult.match({
+  ok: (context) => {
+    // Use context...
+  },
+  err: (error) => {
+    // Handle errors...
+  }
+});
+```
+
+## Using c15t with neverthrow
+
+### Initialization
+
+The c15t library provides two versions of most core functions:
+
+1. Traditional functions that might throw exceptions (for backward compatibility)
+2. New functions with the `WithResult` suffix that return `Result` objects
+
+```typescript
+import { c15tWithResult } from '@c15t/backend';
+import { memoryAdapter } from '@c15t/backend/db/adapters/memory';
+
+// Create a c15t instance with Result-based error handling
+const c15tInstance = c15tWithResult({
+  secret: 'your-secret-key',
+  storage: memoryAdapter(),
+});
+
+// The context is now a ResultAsync
+c15tInstance.$context.match({
+  ok: (context) => {
+    console.log(`Initialized ${context.appName} successfully`);
+  },
+  err: (error) => {
+    console.error(`Initialization failed: ${error.message}`);
+  }
+});
+```
+
+### Request Handling
+
+The Result-based instance provides both traditional and Result-based handlers:
+
+```typescript
+// Traditional approach (might throw)
+app.use('/api/c15t', async (req, res) => {
+  try {
+    const response = await c15tInstance.handler(request);
+    // Handle response...
+  } catch (error) {
+    // Handle error...
+  }
+});
+
+// Result-based approach
+app.use('/api/c15t', async (req, res) => {
+  const requestResult = await c15tInstance.handlerWithResult(request);
+  
+  requestResult.match({
+    ok: (response) => {
+      // Handle successful response...
+    },
+    err: (error) => {
+      // Handle error with structured data...
+    }
+  });
+});
+```
+
+### Error Types
+
+All errors are instances of `C15TError` with properties:
+
+- `message`: Human-readable error message
+- `code`: Error code from `BASE_ERROR_CODES`
+- `status`: HTTP status code when applicable
+- `data`: Additional error data
+
+### Chaining Operations
+
+One of the major benefits of the neverthrow approach is the ability to chain operations with proper error handling:
+
+```typescript
+c15tInstance.$context
+  .andThen(context => {
+    // Use context to perform another operation
+    return c15tInstance.handlerWithResult(request);
+  })
+  .map(response => {
+    // Transform successful response
+    return response.json();
+  })
+  .mapErr(error => {
+    // Transform or enrich error
+    console.error(`Error: ${error.message}`);
+    return error;
+  });
+```
+
+### Combining with Promises
+
+You can convert between Results and Promises:
+
+```typescript
+import { toPromise, fromC15TPromise } from '@c15t/backend/utils';
+
+// Convert Result to Promise (might throw)
+const contextPromise = toPromise(c15tInstance.$context);
+
+// Convert Promise to Result
+const resultFromPromise = fromC15TPromise(somePromise);
+```
+
+## Complete Example
+
+See the complete example at `packages/c15t/src/examples/neverthrow-example.ts`.
+
+## Best Practices
+
+1. **Be explicit about errors**: Use the `match` method to handle both success and error cases explicitly.
+
+2. **Chain operations**: Use `andThen`, `map`, and `mapErr` to chain operations and transformations.
+
+3. **Type your errors**: Make use of error codes to handle specific error conditions.
+
+4. **Avoid mixing patterns**: Stick to either the Result pattern or traditional try/catch within a single function.
+
+5. **Convert at boundaries**: Use conversion utilities when interacting with code that doesn't use the Result pattern.
+
+## Backward Compatibility
+
+The c15t library maintains backward compatibility with the traditional error handling approach. You can continue using the existing API, or gradually migrate to the Result pattern.