@vibesdotdev/storage 0.0.2 → 1.0.0-rc.3

package/src/docs/manifests.docs.descriptor.ts

@@ -1,318 +0,0 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
-
-const descriptor: DocsTopicDescriptor = {
-	kind: 'docs/topic',
-	id: 'storage.manifests',
-	title: 'Storage Manifests',
-	summary: 'Manifest declarations, allowed adapters, and namespace organization',
-	body: {
-		type: 'markdown',
-		sourceType: 'raw',
-		source: `---
-title: Storage Manifests
-summary: Manifest declarations, allowed adapters, and namespace organization
-tags: [storage, manifests, declarations, adapters, namespaces]
-parent: storage
-order: 4
-surfaces: [cli, web, in-app]
-hardware: [consumer, cloud]
----
-
-# Storage Manifests
-
-Manifests declare the structure and storage requirements for a data type. The \`storage/manifest\` runtime kind defines what data to store, which adapters are allowed, and how the data is organized.
-
-## Manifest Structure
-
-\`\`\`ts
-interface StorageManifestDescriptor {
-  kind: 'storage/manifest';
-  id: string;                    // unique identifier
-  namespace: string;             // organizational namespace
-  schema: ZodSchema;             // data validation schema
-  allowedAdapters?: string[];    // allowed adapter IDs
-  adapterConfig?: {
-    [adapterId: string]: {
-      [key: string]: unknown;
-    };
-  };
-  context?: {
-    hardware?: ('consumer' | 'cloud')[];
-    environment?: string[];
-  };
-  enabled?: boolean;
-}
-\`\`\`
-
-## Defining a Manifest
-
-### Basic Manifest
-
-\`\`\`ts
-import { z } from 'zod';
-import type { StorageManifestDescriptor } from '@vibesdotdev/storage';
-
-const settingsManifest: StorageManifestDescriptor = {
-  kind: 'storage/manifest',
-  id: 'app/settings',
-  namespace: 'app',
-  schema: z.object({
-    theme: z.enum(['light', 'dark', 'system']),
-    language: z.string().default('en'),
-    notifications: z.boolean().default(true),
-    autoSave: z.boolean().default(true)
-  })
-};
-\`\`\`
-
-### Manifest with Adapter Constraints
-
-\`\`\`ts
-const userPreferencesManifest: StorageManifestDescriptor = {
-  kind: 'storage/manifest',
-  id: 'user/preferences',
-  namespace: 'user',
-  schema: z.object({
-    // ... schema fields
-  }),
-  allowedAdapters: [
-    'storage.adapter.libsql',
-    'storage.adapter.d1',
-    'storage.adapter.drizzle'
-  ],
-  adapterConfig: {
-    'storage.cloud-api': {
-      endpoint: 'https://storage.vibes.dev/user/preferences'
-    }
-  }
-};
-\`\`\`
-
-### Manifest with Context Rules
-
-\`\`\`ts
-const productionConfigManifest: StorageManifestDescriptor = {
-  kind: 'storage/manifest',
-  id: 'app/production-config',
-  namespace: 'app',
-  schema: z.object({
-    // ... schema fields
-  }),
-  context: {
-    hardware: ['cloud'],
-    environment: ['production']
-  }
-};
-\`\`\`
-
-## Using StorageManifest Class
-
-The \`StorageManifest\` class provides document operations:
-
-\`\`\`ts
-import { StorageManifest } from '@vibesdotdev/storage';
-import { getVibesRuntime } from '@vibesdotdev/runtime';
-
-const runtime = getVibesRuntime();
-
-// Create manifest instance
-const settings = new StorageManifest('app/settings');
-
-// Load data
-const data = await settings.load();
-
-// Save data
-await settings.save({
-  theme: 'dark',
-  language: 'en',
-  notifications: true
-});
-
-// Check existence
-const exists = await settings.exists();
-
-// Delete data
-await settings.delete();
-\`\`\`
-
-## Manifest Namespaces
-
-Namespaces organize manifests hierarchically:
-
-\`\`\`
-app/settings
-app/preferences
-app/theme
-user/profile
-user/preferences
-system/config
-\`\`\`
-
-**Namespace conventions:**
-- \`app/*\` — Application-level configuration
-- \`user/*\` — User-specific data
-- \`system/*\` — System-wide configuration
-- \`workspace/*\` — Workspace-shared data
-
-## Adapter Configuration
-
-Manifests can configure adapter-specific behavior:
-
-### Cloud-API Endpoint
-
-\`\`\`ts
-{
-  adapterConfig: {
-    'storage.cloud-api': {
-      endpoint: 'https://storage.vibes.dev/app/settings',
-      auth: 'bearer-token'
-    }
-  }
-}
-\`\`\`
-
-### Drizzle Table Name
-
-\`\`\`ts
-{
-  adapterConfig: {
-    'storage.adapter.drizzle': {
-      tableName: 'app_settings',
-      schemaName: 'public'
-    }
-  }
-}
-\`\`\`
-
-### LibSQL Database Path
-
-\`\`\`ts
-{
-  adapterConfig: {
-    'storage.adapter.libsql': {
-      dbPath: './data/app.db',
-      authToken: 'optional-token'
-    }
-  }
-}
-\`\`\`
-
-## Manifest Inheritance
-
-Manifests can extend other manifests:
-
-\`\`\`ts
-const baseManifest: StorageManifestDescriptor = {
-  kind: 'storage/manifest',
-  id: 'app/base-settings',
-  namespace: 'app',
-  schema: z.object({
-    theme: z.enum(['light', 'dark']),
-    language: z.string()
-  })
-};
-
-const extendedManifest: StorageManifestDescriptor = {
-  ...baseManifest,
-  id: 'app/extended-settings',
-  schema: baseManifest.schema.extend({
-    notifications: z.boolean(),
-    autoSave: z.boolean()
-  })
-};
-\`\`\`
-
-## Manifest Validation
-
-Manifests validate data on load and save:
-
-\`\`\`ts
-try {
-  const settings = new StorageManifest('app/settings');
-  await settings.save({ theme: 'invalid' });  // fails validation
-} catch (error) {
-  console.error(error);  // ZodError with details
-}
-\`\`\`
-
-## Manifest Migration
-
-Update schemas while maintaining backward compatibility:
-
-\`\`\`ts
-const settingsManifestV2: StorageManifestDescriptor = {
-  kind: 'storage/manifest',
-  id: 'app/settings',
-  namespace: 'app',
-  schema: z.object({
-    theme: z.enum(['light', 'dark', 'system']),
-    language: z.string().default('en'),
-    // New field with default for migration
-    notifications: z.boolean().default(true)
-  }),
-  // Migration transform
-  transform: {
-    fromRow: (row) => ({
-      ...row,
-      notifications: row.notifications ?? true
-    })
-  }
-};
-\`\`\`
-
-## Listing Manifests
-
-List all registered manifests:
-
-\`\`\`bash
-vibes storage list --kind manifest
-\`\`\`
-
-**Output:**
-\`\`\`
-ID                     Namespace    Adapters
-────────────────────────────────────────────────
-app/settings           app          libsql, cloud-api
-user/preferences       user         drizzle, cloud-api
-system/config          system       d1
-\`\`\`
-
-## Manifest Discovery
-
-Query manifests by namespace:
-
-\`\`\`ts
-const appManifests = runtime.query('storage/manifest')
-  .filter(d => d.namespace === 'app')
-  .descriptors();
-
-const cloudManifests = runtime.query('storage/manifest')
-  .filter(d => d.context?.hardware?.includes('cloud'))
-  .descriptors();
-\`\`\`
-
-## Best Practices
-
-1. **Use descriptive IDs** — \`app/settings\` not \`settings\`
-2. **Namespace consistently** — Group related manifests
-3. **Declare adapter constraints** — Be explicit about allowed adapters
-4. **Version schemas** — Use transforms for migrations
-5. **Test with multiple adapters** — Ensure adapter compatibility
-
-:::card{title="See also"}
-- [\`storage.adapters\`](storage.adapters) — Adapter implementations
-- [\`storage.records\`](storage.records) — Record CRUD operations
-- [\`storage.sync\`](storage.sync) — Cross-app synchronization
-- [\`config.manifests\`](config.manifests) — Configuration manifests
-:::
-`
-	},
-	parent: 'storage',
-	order: 4,
-	tags: ['storage', 'manifests', 'declarations', 'adapters', 'namespaces'],
-	surfaces: ['cli', 'web', 'in-app'],
-	hardware: ['consumer', 'cloud'],
-	enabled: true
-};
-
-export default descriptor;

package/src/docs/records.docs.descriptor.ts

@@ -1,271 +0,0 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
-
-const descriptor: DocsTopicDescriptor = {
-	kind: 'docs/topic',
-	id: 'storage.records',
-	title: 'Storage Records',
-	summary: 'Record CRUD operations, typing, validation, and transforms',
-	body: {
-		type: 'markdown',
-		sourceType: 'raw',
-		source: `---
-title: Storage Records
-summary: Record CRUD operations, typing, validation, and transforms
-tags: [storage, records, crud, typing, validation]
-parent: storage
-order: 2
-surfaces: [cli, web, in-app]
-hardware: [consumer, cloud]
----
-
-# Storage Records
-
-Records provide type-safe CRUD operations for structured data. The \`storage/record\` runtime kind defines the interface for single-table operations with automatic validation and timestamps.
-
-## Record Interface
-
-\`\`\`ts
-interface StorageRecordInterface<T extends Record<string, unknown>> {
-  // Create
-  insert(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
-  
-  // Read
-  find(id: string): Promise<T | null>;
-  findAll(query?: QueryFilter<T>): Promise<T[]>;
-  
-  // Update
-  update(id: string, data: Partial<T>): Promise<T>;
-  
-  // Delete
-  delete(id: string): Promise<void>;
-  
-  // Lifecycle
-  dispose(): Promise<void>;
-}
-\`\`\`
-
-## Defining Record Types
-
-Records are defined with Zod schemas:
-
-\`\`\`ts
-import { z } from 'zod';
-import type { StorageRecordDescriptor } from '@vibesdotdev/storage';
-
-const userRecord: StorageRecordDescriptor = {
-  kind: 'storage/record',
-  id: 'user',
-  namespace: 'app',
-  schema: z.object({
-    id: z.string().uuid(),
-    email: z.string().email(),
-    name: z.string().min(1),
-    role: z.enum(['admin', 'user', 'guest']),
-    createdAt: z.coerce.date(),
-    updatedAt: z.coerce.date()
-  })
-};
-\`\`\`
-
-## Using Records
-
-### Creating Records
-
-\`\`\`ts
-import { StorageRecord } from '@vibesdotdev/storage';
-import { getVibesRuntime } from '@vibesdotdev/runtime';
-
-const runtime = getVibesRuntime();
-const userStore = new StorageRecord(userRecord, { runtime });
-
-const user = await userStore.insert({
-  email: 'alice@example.com',
-  name: 'Alice',
-  role: 'user'
-});
-
-console.log(user);
-// { id: 'uuid...', email: 'alice@example.com', name: 'Alice', role: 'user', ... }
-\`\`\`
-
-### Querying Records
-
-\`\`\`ts
-// Find by ID
-const user = await userStore.find('user-id');
-
-// Find all with filter
-const users = await userStore.findAll({
-  where: { role: 'admin' },
-  orderBy: { field: 'createdAt', direction: 'desc' },
-  limit: 10
-});
-
-// Find first match
-const admin = await userStore.findAll({
-  where: { role: 'admin' },
-  limit: 1
-}).then(results => results[0]);
-\`\`\`
-
-### Updating Records
-
-\`\`\`ts
-const updated = await userStore.update('user-id', {
-  name: 'Alice Updated'
-});
-
-// updatedAt is automatically managed
-console.log(updated.updatedAt); // new Date()
-\`\`\`
-
-### Deleting Records
-
-\`\`\`ts
-await userStore.delete('user-id');
-
-// Verify deletion
-const exists = await userStore.find('user-id');
-console.log(exists); // null
-\`\`\`
-
-## Automatic Timestamps
-
-Records automatically manage \`createdAt\` and \`updatedAt\` fields:
-
-- \`createdAt\` — Set on insert, immutable
-- \`updatedAt\` — Updated on every update operation
-
-These fields are added automatically if not in your schema. To disable:
-
-\`\`\`ts
-const record: StorageRecordDescriptor = {
-  ...
-  schema: z.object({
-    // your fields
-  }),
-  timestamps: false  // disable automatic timestamps
-};
-\`\`\`
-
-## Validation
-
-Records validate data against the schema on every operation:
-
-\`\`\`ts
-try {
-  await userStore.insert({
-    email: 'not-an-email',  // fails validation
-    name: 'Bob'
-  });
-} catch (error) {
-  console.error(error);  // ZodError with validation details
-}
-\`\`\`
-
-## Record Transforms
-
-Transforms convert between storage and application formats:
-
-\`\`\`ts
-import { defineStorageTransform } from '@vibesdotdev/storage';
-
-const userTransform = defineStorageTransform({
-  id: 'user.transform',
-  fromRow: (row) => ({
-    ...row,
-    displayName: row.name.toUpperCase()
-  }),
-  toRow: (data) => ({
-    ...data,
-    name: data.displayName.toLowerCase()
-  })
-});
-\`\`\`
-
-Apply transforms when creating the record store:
-
-\`\`\`ts
-const userStore = new StorageRecord(userRecord, {
-  runtime,
-  transform: userTransform
-});
-\`\`\`
-
-## Relations
-
-Records support relations to other records:
-
-\`\`\`ts
-const postRecord: StorageRecordDescriptor = {
-  kind: 'storage/record',
-  id: 'post',
-  namespace: 'app',
-  schema: z.object({
-    id: z.string(),
-    title: z.string(),
-    authorId: z.string().uuid(),
-    content: z.string()
-  }),
-  relations: {
-    author: {
-      type: 'one',
-      target: 'user',
-      foreignKey: 'authorId'
-    }
-  }
-};
-\`\`\`
-
-## Record Events
-
-Records emit lifecycle events:
-
-\`\`\`ts
-import { storageRecordEvents } from '@vibesdotdev/storage';
-
-runtime.registerDescriptor('event', storageRecordEvents.onInsert);
-runtime.registerDescriptor('event', storageRecordEvents.onUpdate);
-runtime.registerDescriptor('event', storageRecordEvents.onDelete);
-
-// Subscribe to events
-runtime.on('storage/record:insert', (event) => {
-  console.log('Record inserted:', event.recordId);
-});
-\`\`\`
-
-## Storage Policy
-
-Records respect storage policies for access control:
-
-\`\`\`ts
-import { StoragePolicyContext } from '@vibesdotdev/storage';
-
-const policyContext: StoragePolicyContext = {
-  userId: 'current-user',
-  roles: ['user'],
-  capabilities: ['storage:read', 'storage:write']
-};
-
-const userStore = new StorageRecord(userRecord, {
-  runtime,
-  context: { 'storage/policy': policyContext }
-});
-\`\`\`
-
-:::card{title="See also"}
-- [\`storage.adapters\`](storage.adapters) — Adapter implementations
-- [\`storage.manifests\`](storage.manifests) — Manifest declarations
-- [\`storage.sync\`](storage.sync) — Cross-app synchronization
-:::
-`
-	},
-	parent: 'storage',
-	order: 2,
-	tags: ['storage', 'records', 'crud', 'typing', 'validation'],
-	surfaces: ['cli', 'web', 'in-app'],
-	hardware: ['consumer', 'cloud'],
-	enabled: true
-};
-
-export default descriptor;