@vibesdotdev/storage 0.0.1 → 1.0.0-rc.3

package/src/schemas/record/relation.ts

@@ -1,49 +0,0 @@
-/**
- * Storage record relation schemas / types.
- *
- * Extracted from `./descriptor.ts` so the record interface module
- * (`../../interfaces/record/interface.ts`) can reference `StorageRelation`
- * without forming a cycle (descriptor.ts itself imports
- * `StorageRecordInterface` from the interface module for its sync /
- * remote context types).
- */
-
-import * as z from 'zod/v4';
-
-/** Relation types for storage records. */
-export const StorageRelationTypeSchema = z.enum([
-	'belongs_to', // Many-to-one (e.g., todo belongs to session)
-	'has_one', // One-to-one (e.g., session has one config)
-	'has_many', // One-to-many (e.g., session has many todos)
-	'many_to_many' // Many-to-many (e.g., user has many roles)
-]);
-
-/** Relation definition for a storage record. */
-export const StorageRelationSchema = z.object({
-	/** Relation type */
-	type: StorageRelationTypeSchema,
-
-	/** Target record descriptor ID (e.g., 'session.sessions') */
-	target: z.string(),
-
-	/** Foreign key field in this table (for belongs_to) */
-	foreignKey: z.string().optional(),
-
-	/** Foreign key field in target table (for has_one/has_many) */
-	foreignKeyTarget: z.string().optional(),
-
-	/** Junction table for many_to_many relations */
-	through: z.string().optional(),
-
-	/** Whether this relation is optional */
-	optional: z.boolean().default(false),
-
-	/** Cascade delete when parent is deleted */
-	cascadeDelete: z.boolean().default(false),
-
-	/** Custom relation name (defaults to property key) */
-	as: z.string().optional()
-});
-
-export type StorageRelationType = z.infer<typeof StorageRelationTypeSchema>;
-export type StorageRelation = z.infer<typeof StorageRelationSchema>;

package/src/schemas/schema/descriptor.ts

@@ -1,278 +0,0 @@
-/**
- * Storage Schema Descriptor Schema
- *
- * Defines a multi-table schema with relations for complex modules.
- * Used for modules that need multiple related tables with foreign keys.
- *
- * @example
- * ```typescript
- * const sessionSchemaDescriptor: StorageSchemaDescriptor = {
- *   kind: 'storage/schema',
- *   id: 'session',
- *   name: 'Session Storage Schema',
- *   description: 'Complete session storage with multiple related tables',
- *   tables: {
- *     sessions: {
- *       schema: SessionSchema,
- *       primaryKey: 'id',
- *       indexes: [{ fields: ['status'] }]
- *     },
- *     todos: {
- *       schema: TodoSchema,
- *       primaryKey: 'id',
- *       relations: {
- *         session: { type: 'belongs_to', target: 'sessions', foreignKey: 'sessionId' }
- *       }
- *     }
- *   },
- *   migrations: () => import('./migrations').then(m => m.SESSION_MIGRATIONS),
- *   allowedAdapters: ['storage.localdb'],
- *   dbName: 'sessions.db'
- * };
- * ```
- */
-
-import * as z from 'zod/v4';
-import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
-import { StorageScopeSchema } from '../manifest-descriptor';
-import {
-	StorageRelationSchema,
-	StorageIndexSchema,
-	StorageMigrationSchema,
-	StorageFieldConfigSchema
-} from '../record/descriptor';
-
-/**
- * Table definition within a schema
- */
-export const StorageTableDefinitionSchema = z.object({
-	/** Zod schema for the table data (stored as unknown, validated at runtime) */
-	schema: z.unknown(),
-
-	/** Primary key field name (default: 'id') */
-	primaryKey: z.string().default('id'),
-
-	/** Relations to other tables in this schema */
-	relations: z.record(z.string(), StorageRelationSchema).optional(),
-
-	/** Database indexes for this table */
-	indexes: z.array(StorageIndexSchema).default([]),
-
-	/** Auto-manage timestamps (createdAt, updatedAt) */
-	timestamps: z
-		.union([
-			z.boolean(),
-			z.object({
-				createdAt: z.union([z.boolean(), z.string()]).optional(),
-				updatedAt: z.union([z.boolean(), z.string()]).optional()
-			})
-		])
-		.default(true),
-
-	/** Auto-generate IDs */
-	autoId: z
-		.union([
-			z.boolean(),
-			z.object({
-				field: z.string().optional(),
-				strategy: z.enum(['uuid', 'nanoid', 'custom']).optional(),
-				generator: z.optional(z.unknown())
-			})
-		])
-		.default(true),
-
-	/** Soft delete field (e.g., 'deletedAt') */
-	softDelete: z.union([z.boolean(), z.string()]).optional(),
-
-	/** Field-specific configurations */
-	fieldConfig: z.record(z.string(), StorageFieldConfigSchema).optional(),
-
-	/** Enable record versioning for optimistic locking */
-	versioning: z.boolean().default(false),
-
-	/** Enable audit trail (createdBy, updatedBy) */
-	audit: z.boolean().default(false),
-
-	/** Enable change tracking for sync */
-	changeTracking: z.boolean().default(false),
-
-	/** Custom validation function */
-	validate: z.optional(z.unknown()),
-
-	/** Before create hook */
-	beforeCreate: z.optional(z.unknown()),
-
-	/** After create hook */
-	afterCreate: z.optional(z.unknown()),
-
-	/** Before update hook */
-	beforeUpdate: z.optional(z.unknown()),
-
-	/** After update hook */
-	afterUpdate: z.optional(z.unknown()),
-
-	/** Before delete hook */
-	beforeDelete: z.optional(z.unknown()),
-
-	/** After delete hook */
-	afterDelete: z.optional(z.unknown())
-});
-
-/**
- * Migration source - can be inline or lazy-loaded
- */
-export const MigrationSourceSchema = z.union([
-	// Inline migrations array
-	z.array(StorageMigrationSchema),
-	// Lazy-loaded migrations (function that returns promise)
-	z.unknown(),
-	// Module import path
-	z.string()
-]);
-
-/**
- * Storage schema descriptor schema
- */
-export const StorageSchemaDescriptorSchema = RuntimeDescriptorSchema.extend({
-	kind: z.literal('storage/schema'),
-
-	// SCHEMA DEFINITION
-
-	/** Human-readable name */
-	name: z.string().min(1),
-
-	/** Human-readable description */
-	description: z.string().optional(),
-
-	/** Table definitions (key is table name) */
-	tables: z
-		.record(z.string(), StorageTableDefinitionSchema)
-		.refine((tables) => Object.keys(tables).length > 0, {
-			message: 'Schema must have at least one table'
-		}),
-
-	// MIGRATIONS
-
-	/** Inline or lazy-loaded migrations for this schema */
-	migrations: MigrationSourceSchema.optional(),
-
-	/** Migration key for external migrations (e.g., 'session') */
-	migrationKey: z.string().optional(),
-
-	/** Current schema version (default: 1) */
-	version: z.number().int().positive().default(1),
-
-	// ADAPTER SELECTION
-
-	/** Allowed adapter IDs (e.g., ['storage.localdb', 'storage.drizzle']) */
-	allowedAdapters: z.array(z.string()).min(1),
-
-	/** Default adapter to use when not specified */
-	defaultAdapter: z.string().optional(),
-
-	/** Adapter-specific configuration */
-	adapterConfig: z.record(z.string(), z.unknown()).optional(),
-
-	// SCOPE & STORAGE
-
-	/** Storage scope for path resolution */
-	scope: StorageScopeSchema.default('project'),
-
-	/** Custom database name (overrides default) */
-	dbName: z.string().optional(),
-
-	/** Database schema name (for Postgres) */
-	dbSchema: z.string().optional(),
-
-	/** Custom base path for database */
-	basePath: z.string().optional(),
-
-	// SCHEMA FEATURES
-
-	/** Enable foreign key constraints */
-	foreignKeys: z.boolean().default(true),
-
-	/** Enable cascade delete for relations with cascadeDelete=true */
-	cascadeDelete: z.boolean().default(true),
-
-	/** Enable transactions for multi-table operations */
-	transactions: z.boolean().default(true),
-
-	/** Enable database connection pooling */
-	pooling: z.boolean().default(true),
-
-	/** Pool size (if pooling enabled) */
-	poolSize: z.number().int().positive().default(5),
-
-	// SYNC & REPLICATION
-
-	/** Enable sync between runtimes */
-	sync: z.boolean().default(false),
-
-	/** Sync configuration */
-	syncConfig: z
-		.object({
-			/** Sync direction */
-			direction: z.enum(['bidirectional', 'to-cloud', 'from-cloud']).default('bidirectional'),
-
-			/** Conflict resolution strategy */
-			conflictResolution: z
-				.enum(['server-wins', 'client-wins', 'timestamp', 'custom'])
-				.default('timestamp'),
-
-			/** Custom conflict resolver */
-			conflictResolver: z.optional(z.unknown()),
-
-			/** Sync interval in milliseconds */
-			interval: z.number().int().positive().default(60000),
-
-			/** Tables to exclude from sync */
-			excludeTables: z.array(z.string()).optional()
-		})
-		.optional(),
-
-	// BACKUP & RESTORE
-
-	/** Enable automatic backups */
-	backup: z.boolean().default(false),
-
-	/** Backup configuration */
-	backupConfig: z
-		.object({
-			/** Backup interval in milliseconds */
-			interval: z.number().int().positive().default(86400000), // 24 hours
-
-			/** Maximum number of backups to keep */
-			maxBackups: z.number().int().positive().default(7),
-
-			/** Backup location */
-			location: z.string().optional(),
-
-			/** Tables to exclude from backup */
-			excludeTables: z.array(z.string()).optional()
-		})
-		.optional(),
-
-	// METADATA
-
-	/** Whether this schema is internal (not user-editable) */
-	internal: z.boolean().default(false),
-
-	/** Schema namespace (e.g., 'session') */
-	namespace: z.string().optional(),
-
-	/** Tags for categorization */
-	tags: z.array(z.string()).default([]),
-
-	/** Schema author/maintainer */
-	author: z.string().optional(),
-
-	/** Schema version history URL */
-	versionHistoryUrl: z.string().optional()
-});
-
-// TYPE EXPORTS
-
-export type StorageTableDefinition = z.infer<typeof StorageTableDefinitionSchema>;
-export type MigrationSource = z.infer<typeof MigrationSourceSchema>;
-export type StorageSchemaDescriptor = z.infer<typeof StorageSchemaDescriptorSchema>;

package/src/schemas/schema/index.ts

@@ -1,14 +0,0 @@
-/**
- * Storage Schema Exports
- *
- * Exports all types and schemas for storage/schema descriptors.
- */
-
-export {
-	StorageSchemaDescriptorSchema,
-	StorageTableDefinitionSchema,
-	MigrationSourceSchema,
-	type StorageSchemaDescriptor,
-	type StorageTableDefinition,
-	type MigrationSource
-} from './descriptor';

package/src/schemas/sync-bridge-descriptor.ts

@@ -1,143 +0,0 @@
-/**
- * Storage Sync-Bridge Descriptor Schema
- *
- * Declares a bidirectional sync bridge between a runtime kind (local descriptors)
- * and a cloud CRUD API. Replaces hand-rolled per-module sync services with a
- * declarative descriptor that the generic sync executor can process.
- *
- * The bridge maps local runtime descriptors ↔ remote API records, handling
- * ID transformation, ownership filtering, secret stripping, and conflict resolution.
- */
-
-import * as z from 'zod/v4';
-import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
-
-export const SyncDirectionSchema = z.enum(['bidirectional', 'push-only', 'pull-only']);
-export type SyncDirection = z.infer<typeof SyncDirectionSchema>;
-
-export const ConflictStrategySchema = z.enum(['local-wins', 'remote-wins', 'manual', 'newest']);
-export type ConflictStrategy = z.infer<typeof ConflictStrategySchema>;
-
-export const OwnershipFilterSchema = z.enum(['all', 'user-only', 'system-only']);
-export type OwnershipFilter = z.infer<typeof OwnershipFilterSchema>;
-
-/**
- * Schema for a sync-bridge descriptor.
- *
- * Extends RuntimeDescriptor with source/target/sync configuration.
- */
-export const SyncBridgeDescriptorSchema = RuntimeDescriptorSchema.extend({
-	kind: z.literal('storage/sync-bridge'),
-
-	/** Source: where descriptors live locally */
-	source: z.object({
-		/** The runtime kind ID to collect descriptors from (e.g. 'dev/benchmark-suite') */
-		runtimeKind: z.string().min(1),
-
-		/** Optional: field on the descriptor that holds the version number */
-		versionField: z.string().optional(),
-
-		/** Optional: field on the descriptor that holds the source type ('system' | 'user') */
-		sourceTypeField: z.string().optional()
-	}),
-
-	/** Target: the cloud CRUD API to sync against */
-	target: z.object({
-		/** API path for the collection endpoint (e.g. '/api/dev/benchmarks') */
-		apiPath: z.string().min(1),
-
-		/** API path for a single entity, with :id placeholder (e.g. '/api/dev/benchmarks/:id') */
-		entityPath: z.string().optional(),
-
-		/** The field name in API responses that contains the list of items */
-		listField: z.string().optional(),
-
-		/** The field name for the total count in list responses */
-		totalField: z.string().optional(),
-
-		/** Request soft-deleted rows when the remote API supports it */
-		includeDeleted: z.boolean().optional()
-	}),
-
-	/** Sync behavior configuration */
-	sync: z
-		.object({
-			/** Sync direction */
-			direction: SyncDirectionSchema.default('bidirectional'),
-
-			/** Which entities to sync based on ownership */
-			ownershipFilter: OwnershipFilterSchema.default('all'),
-
-			/** How to handle conflicts when both sides changed */
-			conflictStrategy: ConflictStrategySchema.default('local-wins'),
-
-			/** Fields to strip before pushing to cloud (e.g. secrets) */
-			sensitiveFields: z.array(z.string()).default([]),
-
-			/** The field that uniquely identifies an entity */
-			idField: z.string().default('id')
-		})
-		.default({
-			direction: 'bidirectional',
-			ownershipFilter: 'all',
-			conflictStrategy: 'local-wins',
-			sensitiveFields: [],
-			idField: 'id'
-		})
-}).passthrough();
-
-export type SyncBridgeDescriptor = z.infer<typeof SyncBridgeDescriptorSchema> & {
-	/**
-	 * Transform a local runtime descriptor into the shape the API expects.
-	 * Called before pushing to cloud.
-	 */
-	toRemote?: (descriptor: Record<string, unknown>) => Record<string, unknown>;
-
-	/**
-	 * Transform an API response record into a local runtime descriptor shape.
-	 * Called after pulling from cloud.
-	 */
-	fromRemote?: (record: Record<string, unknown>) => Record<string, unknown>;
-
-	/**
-	 * Optional: Ensure remote prerequisites exist before pushing an entity.
-	 * Useful when the remote API expects related resources (for example, a
-	 * knowledge base) to exist before an item can be upserted.
-	 */
-	beforePush?: (
-		descriptor: Record<string, unknown>,
-		context: {
-			apiEndpoint: string;
-			apiToken?: string;
-			fetch: (input: string, init?: RequestInit) => Promise<Response>;
-		}
-	) => Promise<void>;
-
-	deleteRemote?: (
-		descriptor: Record<string, unknown>,
-		context: {
-			apiEndpoint: string;
-			apiToken?: string;
-			fetch: (input: string, init?: RequestInit) => Promise<Response>;
-		}
-	) => Promise<void>;
-
-	/**
-	 * Optional: Custom collection function. Defaults to runtime.query(source.runtimeKind).descriptors()
-	 */
-	collect?: () => Promise<Record<string, unknown>[]> | Record<string, unknown>[];
-
-	/**
-	 * Optional: Storage manifest ID for persisting pulled items.
-	 * When set, pulled items are merged into this storage manifest (localdb/json).
-	 * When omitted, pulled items are only registered with the runtime (descriptor-only bridges).
-	 */
-	storageManifestId?: string;
-
-	/**
-	 * Optional: Custom write function for pulled items.
-	 * Called when a remote-only item needs to be persisted locally.
-	 * When omitted and storageManifestId is set, uses StorageManifest.load/save.
-	 */
-	writePulled?: (items: Record<string, unknown>[]) => Promise<void>;
-};