@vibesdotdev/storage 0.0.1

package/src/schemas/record/descriptor.ts

@@ -0,0 +1,621 @@
+/**
+ * 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

@@ -0,0 +1,60 @@
+/**
+ * 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';