@vibesdotdev/storage 0.0.2 → 1.0.0-rc.3

package/src/schemas/record/descriptor.ts

@@ -1,621 +0,0 @@
-/**
- * Storage Record Descriptor Schema
- *
- * Defines a record type that provides CRUD operations on a single table.
- * Used for modules that need structured storage with relations and queries.
- *
- * @example
- * ```typescript
- * const todoDescriptor: StorageRecordDescriptor = {
- *   kind: 'storage/record',
- *   id: 'session.todos',
- *   name: 'Session Todos',
- *   description: 'Todo items within sessions',
- *   schema: TodoSchema,
- *   tableName: 'todos',
- *   primaryKey: 'id',
- *   relations: {
- *     session: {
- *       type: 'belongs_to',
- *       target: 'session.sessions',
- *       foreignKey: 'sessionId'
- *     }
- *   },
- *   fts: {
- *     fields: ['content', 'activeForm']
- *   },
- *   hierarchy: {
- *     parentField: 'parentId'
- *   },
- *   allowedAdapters: ['storage.localdb'],
- *   defaultAdapter: 'storage.localdb'
- * };
- * ```
- */
-
-import * as z from 'zod/v4';
-import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
-import { StorageScopeSchema } from '../manifest-descriptor';
-import { ConflictStrategySchema } from '../sync-bridge-descriptor';
-import type { VibesRuntime } from '@vibesdotdev/runtime';
-import type { StorageRecordInterface } from '../../interfaces/record/interface';
-
-// RELATION TYPES
-
-export { StorageRelationSchema, StorageRelationTypeSchema } from './relation';
-export type { StorageRelation, StorageRelationType } from './relation';
-import { StorageRelationSchema } from './relation';
-
-// INDEX TYPES
-
-/**
- * Index definition for a storage record
- */
-export const StorageIndexSchema = z.object({
-	/** Index name (auto-generated if not provided) */
-	name: z.string().optional(),
-
-	/** Fields to index */
-	fields: z.array(z.string()).min(1),
-
-	/** Whether this is a unique index */
-	unique: z.boolean().default(false),
-
-	/** Custom index type (e.g., 'btree', 'hash') */
-	type: z.string().optional(),
-
-	/** Index condition (partial index) */
-	where: z.string().optional()
-});
-
-// MIGRATION TYPES
-
-/**
- * Migration definition for storage records
- */
-export const StorageMigrationSchema = z.object({
-	/** Migration version number */
-	version: z.number().int().positive(),
-
-	/** Migration name/description */
-	name: z.string().optional(),
-
-	/** Up migration SQL or function */
-	up: z.union([z.string(), z.unknown()]),
-
-	/** Down migration SQL or function */
-	down: z.union([z.string(), z.unknown()]).optional()
-});
-
-// FIELD CONFIG TYPES
-
-/**
- * Field configuration for auto-managed fields
- */
-export const StorageFieldConfigSchema = z.object({
-	/** Enable auto-increment */
-	autoIncrement: z.boolean().optional(),
-
-	/** Custom ID generator function */
-	generator: z.optional(z.unknown()),
-
-	/** Field type override */
-	type: z.string().optional(),
-
-	/** Default value */
-	default: z.unknown().optional()
-});
-
-// FTS (FULL-TEXT SEARCH) TYPES
-
-/**
- * FTS configuration for storage records
- */
-export const StorageFtsConfigSchema = z.object({
-	/** Fields to index for search */
-	fields: z.array(z.string()).min(1),
-
-	/** FTS tokenizer (SQLite: 'unicode61', 'porter', etc.) */
-	tokenizer: z.string().optional(),
-
-	/** Custom FTS table name (default: {tableName}_fts) */
-	tableName: z.string().optional(),
-
-	/** Additional FTS options */
-	options: z.record(z.string(), z.unknown()).optional()
-});
-
-// COMPUTED FIELD TYPES
-
-/**
- * Computed field definition
- */
-export const StorageComputedFieldSchema = z.object({
-	/** Aggregation type */
-	type: z.enum(['count', 'sum', 'avg', 'min', 'max', 'exists']),
-
-	/** Relation to aggregate over */
-	relation: z.string(),
-
-	/** Field on related table to aggregate (for sum/avg/min/max) */
-	field: z.string().optional(),
-
-	/** Filter conditions on related records */
-	where: z.record(z.string(), z.unknown()).optional(),
-
-	/** Custom SQL expression (overrides type/relation) */
-	expression: z.string().optional(),
-
-	/** Cache the computed value in database */
-	cached: z.boolean().default(false),
-
-	/** Cache invalidation strategy */
-	cacheStrategy: z.enum(['on_write', 'manual', 'ttl']).optional(),
-
-	/** Cache TTL in seconds (for ttl strategy) */
-	cacheTtl: z.number().int().positive().optional()
-});
-
-// HIERARCHY TYPES
-
-/**
- * Hierarchy configuration for recursive data
- */
-export const StorageHierarchyConfigSchema = z.object({
-	/** Field that references parent (e.g., 'parentId') */
-	parentField: z.string(),
-
-	/** Relation name for children (default: derived from tableName) */
-	childrenRelation: z.string().optional(),
-
-	/** Include depth in recursive query results */
-	includeDepth: z.boolean().default(true),
-
-	/** Include path from root in results */
-	includePath: z.boolean().default(false),
-
-	/** Maximum recursion depth (default: unlimited) */
-	maxDepth: z.number().int().positive().optional()
-});
-
-// REMOTE ADAPTER CONFIGURATION
-
-/**
- * Remote CRUD configuration for cloud sync
- */
-export const StorageRemoteCrudSchema = z.object({
-	/** Base API path for list operations */
-	apiPath: z.string(),
-
-	/** API path for single entity operations (:id placeholder) */
-	entityPath: z.string().optional(),
-
-	/** Remote list response field (defaults to items) */
-	listField: z.string().optional(),
-
-	/** Remote total response field */
-	totalField: z.string().optional(),
-
-	/** HTTP method for updates (PUT, PATCH, etc.) */
-	updateMethod: z.enum(['PUT', 'PATCH']).default('PUT'),
-
-	/** HTTP method for creates (POST, PUT) */
-	createMethod: z.enum(['POST', 'PUT']).default('POST'),
-
-	/** HTTP method for deletes (DELETE) */
-	deleteMethod: z.literal('DELETE').default('DELETE')
-});
-
-/**
- * Remote adapter configuration
- */
-export const StorageRemoteConfigSchema = z.object({
-	/** Remote adapter ID (typically 'storage.cloud-api') */
-	adapter: z.string().default('storage.cloud-api'),
-
-	/** CRUD endpoint configuration */
-	crud: StorageRemoteCrudSchema.optional()
-});
-
-// PERSISTENCE POLICY
-
-/**
- * Persistence mode for data storage
- */
-export const StoragePersistenceModeSchema = z.enum([
-	'local-only', // Store only locally
-	'remote-only', // Store only in cloud
-	'local-first', // Local primary, sync to cloud
-	'remote-first', // Cloud primary, cache locally
-	'auto' // Auto-detect based on connectivity
-]);
-
-/**
- * Persistence policy configuration
- */
-export const StoragePersistencePolicySchema = z.object({
-	/** Persistence mode */
-	mode: StoragePersistenceModeSchema,
-
-	/** Adapters for local storage */
-	localAdapters: z.array(z.string()).optional(),
-
-	/** Adapters for remote storage */
-	remoteAdapters: z.array(z.string()).optional()
-});
-
-// SYNC CONFIGURATION
-
-/**
- * Ownership filter for sync operations
- */
-export const StorageOwnershipFilterSchema = z.enum([
-	'all', // Sync all records
-	'user-only', // Only user-created records
-	'system-only' // Only system records
-]);
-
-/**
- * Sync configuration for storage records
- */
-export const StorageSyncConfigSchema = z.object({
-	/** Ownership filter */
-	ownershipFilter: StorageOwnershipFilterSchema.default('all'),
-
-	/** Optional field used as canonical ID for sync matching */
-	idField: z.string().optional(),
-
-	/** Strategy used when both local and remote diverge */
-	conflictStrategy: ConflictStrategySchema.default('local-wins'),
-
-	/** Fields to strip before pushing to remote */
-	sensitiveFields: z.array(z.string()).default([]),
-
-	/** Function to collect local items for sync */
-	collect: z.optional(z.unknown()),
-
-	/** Function to transform local record before sync */
-	toRemote: z.optional(z.unknown()),
-
-	/** Function to transform remote record into local shape */
-	fromRemote: z.optional(z.unknown()),
-
-	/** Hook called before pushing to remote */
-	beforePush: z.optional(z.unknown()),
-
-	/** Hook called to delete remote row */
-	deleteRemote: z.optional(z.unknown()),
-
-	/** Hook for writing pulled remote rows locally */
-	writePulled: z.optional(z.unknown())
-});
-
-export type StorageSyncContext = {
-	runtime: VibesRuntime;
-	record?: StorageRecordInterface<unknown>;
-	apiEndpoint: string;
-	apiToken?: string;
-	fetch: (input: string, init?: RequestInit) => Promise<Response>;
-};
-
-export type StorageRecordLocalSyncContext = {
-	runtime: VibesRuntime;
-	record: StorageRecordInterface<Record<string, unknown>>;
-	apiEndpoint?: never;
-	apiToken?: never;
-	fetch?: never;
-};
-
-export type StorageRecordRemoteSyncContext = {
-	runtime: VibesRuntime;
-	record?: never;
-	apiEndpoint: string;
-	apiToken?: string;
-	fetch: (input: string, init?: RequestInit) => Promise<Response>;
-};
-
-export type StorageRecordSyncHooks = {
-	collect?: (context: StorageRecordLocalSyncContext) => Promise<Record<string, unknown>[]>;
-	toRemote?: (
-		item: Record<string, unknown>,
-		context?: StorageRecordLocalSyncContext
-	) => Record<string, unknown>;
-	fromRemote?: (item: Record<string, unknown>) => Record<string, unknown>;
-	beforePush?: (
-		item: Record<string, unknown>,
-		context: StorageRecordRemoteSyncContext
-	) => Promise<void>;
-	deleteRemote?: (
-		item: Record<string, unknown>,
-		context: StorageRecordRemoteSyncContext
-	) => Promise<void>;
-	writePulled?: (
-		items: Record<string, unknown>[],
-		context: StorageRecordLocalSyncContext
-	) => Promise<void>;
-};
-
-/**
- * Side effect operation types
- */
-export const StorageSideEffectOperationSchema = z.enum([
-	'update', // Update field(s) on target
-	'touch', // Update timestamp field on target
-	'increment', // Increment numeric field
-	'decrement', // Decrement numeric field
-	'refresh' // Refresh computed field
-]);
-
-/**
- * Side effect definition
- */
-export const StorageSideEffectSchema = z.object({
-	/** Target storage record ID */
-	target: z.string(),
-
-	/** Operation to perform */
-	operation: StorageSideEffectOperationSchema,
-
-	/** Field to update on target (for update/touch) */
-	field: z.string().optional(),
-
-	/** Value to set (for update) or expression */
-	value: z.unknown().optional(),
-
-	/** Value generator function (receives source record) */
-	valueFn: z.optional(z.unknown()),
-
-	/** Foreign key field to find target record */
-	foreignKey: z.string().optional(),
-
-	/** Whether to execute in same transaction */
-	sameTransaction: z.boolean().default(true),
-
-	/** Whether to continue if target not found */
-	ignoreMissing: z.boolean().default(true)
-});
-
-/**
- * Side effects configuration by operation
- */
-export const StorageSideEffectsConfigSchema = z.object({
-	/** Side effects on create */
-	onCreate: z.array(StorageSideEffectSchema).optional(),
-
-	/** Side effects on update */
-	onUpdate: z.array(StorageSideEffectSchema).optional(),
-
-	/** Side effects on delete */
-	onDelete: z.array(StorageSideEffectSchema).optional()
-});
-
-// STORAGE RECORD DESCRIPTOR
-
-/**
- * Storage record descriptor schema
- */
-export const StorageRecordDescriptorSchema = RuntimeDescriptorSchema.extend({
-	kind: z.literal('storage/record'),
-
-	// DATA DEFINITION
-
-	/** Human-readable name */
-	name: z.string().min(1),
-
-	/** Human-readable description */
-	description: z.string().optional(),
-
-	/** Zod schema for the record data (stored as unknown, validated at runtime) */
-	schema: z.unknown(),
-
-	/** Table name in the database */
-	tableName: z.string().min(1),
-
-	/** Primary key field name (default: 'id') */
-	primaryKey: z.string().default('id'),
-
-	// RELATIONS
-
-	/** Relations to other storage records */
-	relations: z.record(z.string(), StorageRelationSchema).optional(),
-
-	// INDEXES
-
-	/** Database indexes for this table */
-	indexes: z.array(StorageIndexSchema).default([]),
-
-	// FULL-TEXT SEARCH
-
-	/** Full-text search configuration */
-	fts: StorageFtsConfigSchema.optional(),
-
-	// COMPUTED FIELDS
-
-	/** Computed fields from aggregations or relations */
-	computedFields: z.record(z.string(), StorageComputedFieldSchema).optional(),
-
-	// HIERARCHY (RECURSIVE)
-
-	/** Hierarchical/recursive configuration */
-	hierarchy: StorageHierarchyConfigSchema.optional(),
-
-	// SIDE EFFECTS
-
-	/** Side effects triggered by operations on this record */
-	sideEffects: StorageSideEffectsConfigSchema.optional(),
-
-	// MIGRATIONS
-
-	/** Inline migration definitions */
-	migrations: z.array(StorageMigrationSchema).optional(),
-
-	/** Migration key for external migrations (e.g., 'session.todos') */
-	migrationKey: z.string().optional(),
-
-	/** Current schema version (default: 1) */
-	version: z.number().int().positive().default(1),
-
-	// AUTO-MANAGED FIELDS
-
-	/** 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(),
-
-	// 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(),
-
-	// FEATURES
-
-	/** 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),
-
-	// VALIDATION
-
-	/** Custom validation function */
-	validate: z.optional(z.unknown()),
-
-	/** Enable schema validation on write */
-	validateOnWrite: z.boolean().default(true),
-
-	/** Enable schema validation on read */
-	validateOnRead: z.boolean().default(false),
-
-	// HOOKS
-
-	/** 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()),
-
-	// METADATA
-
-	/** Whether this record is internal (not user-editable) */
-	internal: z.boolean().default(false),
-
-	/** Record namespace (e.g., 'session.todos') */
-	namespace: z.string().optional(),
-
-	/** Tags for categorization */
-	tags: z.array(z.string()).default([]),
-
-	// REMOTE & SYNC CONFIGURATION
-
-	/** Remote adapter configuration for cloud sync */
-	remote: StorageRemoteConfigSchema.optional(),
-
-	/** Persistence policy for local/remote storage */
-	persistence: StoragePersistencePolicySchema.optional(),
-
-	/** Sync configuration for bidirectional sync */
-	sync: StorageSyncConfigSchema.optional()
-});
-
-// TYPE EXPORTS
-//
-// Two named roles per the schemas-first vision:
-//   * `*Descriptor`      — output of `.parse()`. Defaults applied. What the
-//                          runtime hands to consumers (StorageRecord, sync
-//                          bridges, registration code).
-//   * `*DescriptorInput` — `z.input` of the same schema. What descriptor
-//                          AUTHORS write as a literal: defaults are optional,
-//                          coercions accept their input form. Use this when
-//                          declaring `const x: StorageRecordDescriptorInput =
-//                          { ... }` in record-descriptor source files.
-//
-// The runtime parses input → output at registration time; downstream code
-// always sees the output type. Mixing these breaks descriptor authoring (you
-// have to spell every default explicitly to satisfy the output shape) and
-// breaks consumers (you lose default-applied invariants if you try to read
-// the input shape).
-
-// StorageRelation/StorageRelationType are re-exported above from './relation'.
-export type StorageIndex = z.infer<typeof StorageIndexSchema>;
-export type StorageIndexInput = z.input<typeof StorageIndexSchema>;
-export type StorageMigration = z.infer<typeof StorageMigrationSchema>;
-export type StorageMigrationInput = z.input<typeof StorageMigrationSchema>;
-export type StorageFieldConfig = z.infer<typeof StorageFieldConfigSchema>;
-export type StorageFieldConfigInput = z.input<typeof StorageFieldConfigSchema>;
-export type StorageFtsConfig = z.infer<typeof StorageFtsConfigSchema>;
-export type StorageFtsConfigInput = z.input<typeof StorageFtsConfigSchema>;
-export type StorageComputedField = z.infer<typeof StorageComputedFieldSchema>;
-export type StorageComputedFieldInput = z.input<typeof StorageComputedFieldSchema>;
-export type StorageHierarchyConfig = z.infer<typeof StorageHierarchyConfigSchema>;
-export type StorageHierarchyConfigInput = z.input<typeof StorageHierarchyConfigSchema>;
-export type StorageSideEffectOperation = z.infer<typeof StorageSideEffectOperationSchema>;
-export type StorageSideEffect = z.infer<typeof StorageSideEffectSchema>;
-export type StorageSideEffectInput = z.input<typeof StorageSideEffectSchema>;
-export type StorageSideEffectsConfig = z.infer<typeof StorageSideEffectsConfigSchema>;
-export type StorageSideEffectsConfigInput = z.input<typeof StorageSideEffectsConfigSchema>;
-export type StorageRecordDescriptor = z.infer<typeof StorageRecordDescriptorSchema>;
-export type StorageRecordDescriptorInput = z.input<typeof StorageRecordDescriptorSchema>;
-
-// Remote & Sync types
-export type StorageRemoteCrud = z.infer<typeof StorageRemoteCrudSchema>;
-export type StorageRemoteConfig = z.infer<typeof StorageRemoteConfigSchema>;
-export type StoragePersistenceMode = z.infer<typeof StoragePersistenceModeSchema>;
-export type StoragePersistencePolicy = z.infer<typeof StoragePersistencePolicySchema>;
-export type StorageOwnershipFilter = z.infer<typeof StorageOwnershipFilterSchema>;
-export type StorageSyncConfig = z.infer<typeof StorageSyncConfigSchema>;

package/src/schemas/record/index.ts

@@ -1,60 +0,0 @@
-/**
- * Storage Record Schema Exports
- *
- * Exports all types and schemas for storage/record descriptors.
- */
-
-export {
-	StorageRecordDescriptorSchema,
-	StorageRelationTypeSchema,
-	StorageRelationSchema,
-	StorageSyncConfigSchema,
-	StorageIndexSchema,
-	StorageMigrationSchema,
-	StorageRemoteCrudSchema,
-	StorageRemoteConfigSchema,
-	StoragePersistenceModeSchema,
-	StoragePersistencePolicySchema,
-	StorageOwnershipFilterSchema,
-	StorageFieldConfigSchema,
-	StorageFtsConfigSchema,
-	StorageComputedFieldSchema,
-	StorageHierarchyConfigSchema,
-	StorageSideEffectOperationSchema,
-	StorageSideEffectSchema,
-	StorageSideEffectsConfigSchema
-} from './descriptor';
-
-export type {
-	StorageRecordDescriptor,
-	StorageRecordDescriptorInput,
-	StorageSyncConfig,
-	StorageRemoteCrud,
-	StorageRemoteConfig,
-	StoragePersistenceMode,
-	StoragePersistencePolicy,
-	StorageOwnershipFilter,
-	StorageRelationType,
-	StorageRelation,
-	StorageIndex,
-	StorageIndexInput,
-	StorageMigration,
-	StorageMigrationInput,
-	StorageSyncContext,
-	StorageRecordLocalSyncContext,
-	StorageRecordRemoteSyncContext,
-	StorageRecordSyncHooks,
-	StorageFieldConfig,
-	StorageFieldConfigInput,
-	StorageFtsConfig,
-	StorageFtsConfigInput,
-	StorageComputedField,
-	StorageComputedFieldInput,
-	StorageHierarchyConfig,
-	StorageHierarchyConfigInput,
-	StorageSideEffectOperation,
-	StorageSideEffect,
-	StorageSideEffectInput,
-	StorageSideEffectsConfig,
-	StorageSideEffectsConfigInput
-} from './descriptor';