@paralect/hive 0.1.48 → 0.1.50-alpha.0

package/starter/.cursor/skills/hive-database/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: hive-database
+description: Database operations in Hive framework
+globs:
+  - src/**/*.js
+alwaysApply: false
+---
+
+# Database Operations
+
+## Access Service
+
+```javascript
+import db from 'db';
+const taskService = db.services.tasks;  // From schema name
+```
+
+## Find Operations
+
+```javascript
+// Find many
+const { results, pagesCount, count } = await service.find(
+  { status: 'active' },
+  { page: 1, perPage: 20, sort: '-createdOn', fields: ['_id', 'title'] }
+);
+
+// Find one
+const doc = await service.findOne({ _id: id });
+
+// Check exists
+const exists = await service.exists({ _id: id });
+
+// Count
+const total = await service.count({ status: 'active' });
+
+// Distinct values
+const statuses = await service.distinct('status');
+
+// Aggregate
+const { results } = await service.aggregate([
+  { $match: { status: 'done' } },
+  { $group: { _id: '$project._id', count: { $sum: 1 } } },
+]);
+```
+
+## Write Operations
+
+```javascript
+// Create
+const doc = await service.create({ title: 'New', user: ctx.state.user });
+
+// Update one (must use function)
+const updated = await service.updateOne(
+  { _id: id },
+  (doc) => ({ ...doc, title: 'Updated' })
+);
+
+// Update many
+await service.updateMany(
+  { status: 'pending' },
+  (doc) => ({ ...doc, status: 'active' })
+);
+
+// Remove
+await service.remove({ _id: id });
+
+// Generate ID
+const newId = service.generateId();
+```
+
+## Atomic Operations (No Events)
+
+```javascript
+// Silent bulk update
+await service.atomic.update(
+  { 'project._id': projectId },
+  { $set: { 'project.name': newName } },
+  { multi: true }
+);
+```
+
+## Query Patterns
+
+```javascript
+import { when } from 'services/utils';
+
+const { results } = await service.find({
+  // Conditional fields
+  ...when(status, { status }),
+  ...when(userId, { 'user._id': userId }),
+  
+  // Complex conditions
+  status: { $in: ['active', 'pending'] },
+  createdOn: { $gte: startDate, $lt: endDate },
+  $or: [{ 'user._id': id }, { isPublic: true }],
+});
+```
+
+## Rules
+
+- `updateOne` requires a function, not an object
+- Use `atomic.update` for bulk/silent updates
+- Use `when()` helper for conditional query building

package/starter/.cursor/skills/hive-endpoint/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: hive-endpoint
+description: How to create API endpoints in Hive framework
+globs:
+  - src/resources/**/endpoints/*.js
+alwaysApply: false
+---
+
+# Creating Endpoints
+
+Location: `/src/resources/{name}/endpoints/{action}.js`
+
+## Template (4 Required Exports)
+
+```javascript
+import { z } from 'zod';
+import db from 'db';
+
+const myService = db.services.myResource;
+
+export const handler = async (ctx) => {
+  const { param } = ctx.validatedData;
+  // Logic here
+  return { result: 'data' };
+};
+
+export const middlewares = [];
+
+export const endpoint = {
+  url: '/',
+  method: 'get',
+};
+
+export const requestSchema = z.object({
+  param: z.coerce.string().nullable().optional(),
+});
+```
+
+## Handler Context (ctx)
+
+```javascript
+ctx.validatedData       // Validated input (body + query + params)
+ctx.state.user          // Authenticated user
+ctx.params              // URL params
+ctx.throw(404, 'msg')   // Throw error
+ctx.assert(cond, 400)   // Assert or throw
+```
+
+## Common Patterns
+
+**List:**
+```javascript
+export const handler = async (ctx) => {
+  const { page, perPage } = ctx.validatedData;
+  const { results, count } = await service.find(
+    { 'user._id': ctx.state.user._id },
+    { page, perPage, sort: '-createdOn' }
+  );
+  return { results, count };
+};
+export const endpoint = { url: '/', method: 'get' };
+```
+
+**Create:**
+```javascript
+export const handler = async (ctx) => {
+  const doc = await service.create({
+    ...ctx.validatedData,
+    user: ctx.state.user,
+  });
+  return doc;
+};
+export const endpoint = { url: '/', method: 'post' };
+```
+
+**Update:**
+```javascript
+export const handler = async (ctx) => {
+  const { id, title } = ctx.validatedData;
+  return await service.updateOne({ _id: id }, (doc) => ({ ...doc, title }));
+};
+export const endpoint = { url: '/:id', method: 'put' };
+```
+
+## Middlewares
+
+```javascript
+// By name
+export const middlewares = ['allowNoAuth'];
+
+// With args
+export const middlewares = [{ name: 'shouldExist', args: ['projects'] }];
+
+// Direct function
+import canEditProject from 'middlewares/canEditProject';
+export const middlewares = [canEditProject((ctx) => ctx.params.projectId)];
+```
+
+## Public Endpoint (No Auth)
+
+```javascript
+export const middlewares = ['allowNoAuth'];
+```

package/starter/.cursor/skills/hive-handler/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: hive-handler
+description: How to create event handlers in Hive framework
+globs:
+  - src/resources/**/handlers/*.js
+alwaysApply: false
+---
+
+# Creating Event Handlers
+
+Handlers react to database events automatically.
+
+Location: `/src/resources/{name}/handlers/{handlerName}.js`
+
+## Template
+
+```javascript
+import db from 'db';
+
+const myService = db.services.myResource;
+
+myService.on('created', async ({ doc }) => {
+  // Handle creation
+});
+
+myService.on('updated', async ({ doc, prevDoc }) => {
+  // Handle update
+});
+
+myService.on('removed', async ({ doc }) => {
+  // Handle removal
+});
+```
+
+## Events
+
+| Event | Payload | Trigger |
+|-------|---------|---------|
+| `created` | `{ doc }` | After `service.create()` |
+| `updated` | `{ doc, prevDoc }` | After `service.updateOne/Many()` |
+| `removed` | `{ doc }` | After `service.remove()` |
+
+## Common Patterns
+
+**Create related record:**
+```javascript
+taskService.on('created', async ({ doc }) => {
+  await eventService.create({
+    type: 'task.created',
+    data: { task: doc },
+    project: doc.project,
+  });
+});
+```
+
+**Update parent on child change:**
+```javascript
+docService.on('created', async ({ doc }) => {
+  if (doc.role === 'case-study') {
+    await projectService.updateOne(
+      { _id: doc.project._id },
+      (p) => ({ ...p, caseStudy: doc })
+    );
+  }
+});
+```
+
+**React to specific field change:**
+```javascript
+import ifUpdated from 'helpers/db/ifUpdated';
+
+taskService.on('updated', ifUpdated(['status'], async ({ doc, prevDoc }) => {
+  // Only runs when status changed
+}));
+```
+
+**Cleanup on delete:**
+```javascript
+docService.on('removed', async ({ doc }) => {
+  await eventService.remove({ 'data.doc._id': doc._id });
+});
+```
+
+## Rules
+
+- Keep handlers fast (don't block response)
+- Use `atomic.update` for silent bulk updates (no events)
+- Use `ifUpdated` helper to filter field changes

package/starter/.cursor/skills/hive-mapping/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: hive-mapping
+description: Schema mappings for auto-syncing embedded documents
+globs:
+  - src/autoMap/schemaMappings.json
+alwaysApply: false
+---
+
+# Schema Mappings
+
+Auto-sync embedded references when source documents change.
+
+Location: `/src/autoMap/schemaMappings.json`
+
+## How It Works
+
+1. You embed document references in schemas (e.g., `user: { _id, fullName }`)
+2. You register the mapping in `schemaMappings.json`
+3. When source document updates, all referencing documents sync automatically
+
+## Config Format
+
+```json
+{
+  "tasks": {
+    "user": {
+      "schema": "users"
+    },
+    "project": {
+      "schema": "projects"
+    }
+  }
+}
+```
+
+Means: In `tasks` collection, fields `user` and `project` reference `users` and `projects` collections.
+
+## Example
+
+**Schema with embedded reference:**
+```javascript
+// tasks.schema.js
+project: z
+  .object({
+    _id: z.string(),
+    name: z.coerce.string().nullable().optional(),
+    logoUrl: z.coerce.string().nullable().optional(),
+  })
+  .nullable()
+  .optional(),
+```
+
+**Mapping config:**
+```json
+{
+  "tasks": {
+    "project": {
+      "schema": "projects"
+    }
+  }
+}
+```
+
+**Result:** When project's `name` or `logoUrl` changes, all tasks with that project update automatically.
+
+## Adding New Mapping
+
+1. Define embedded reference in schema (include fields to sync)
+2. Add entry to `schemaMappings.json`:
+
+```json
+{
+  "yourResource": {
+    "fieldName": {
+      "schema": "sourceSchema"
+    }
+  }
+}
+```
+
+## Rules
+
+- Only fields defined in the embedded object shape are synced
+- Works for both single references and arrays
+- Changes sync on source document `updated` event

package/starter/.cursor/skills/hive-middleware/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: hive-middleware
+description: How to create and use middlewares in Hive framework
+globs:
+  - src/middlewares/*.js
+alwaysApply: false
+---
+
+# Middlewares
+
+Location: `/src/middlewares/{name}.js`
+
+## Built-in Middlewares
+
+| Name | Purpose |
+|------|---------|
+| `allowNoAuth` | Skip authentication |
+| `isAuthorized` | Require authenticated user |
+| `shouldExist` | Load resource, 404 if not found |
+| `attachUser` | Load user from token |
+
+## Creating Middleware
+
+**Simple:**
+```javascript
+export default async (ctx, next) => {
+  // Before handler
+  if (!ctx.state.user?.isAdmin) {
+    ctx.throw(403, 'Admin only');
+  }
+  return next();  // Don't forget!
+};
+```
+
+**With parameters:**
+```javascript
+export default (resourceName) => async (ctx, next) => {
+  const doc = await db.services[resourceName].findOne({
+    _id: ctx.params[`${resourceName}Id`],
+  });
+  
+  if (!doc) ctx.throw(404, `${resourceName} not found`);
+  
+  ctx.state[resourceName] = doc;
+  return next();
+};
+```
+
+**With runOrder (lower runs first):**
+```javascript
+const middleware = async (ctx, next) => {
+  ctx.state.isSkipAuth = true;
+  return next();
+};
+middleware.runOrder = -1;
+export default middleware;
+```
+
+## Using in Endpoints
+
+```javascript
+// By name
+export const middlewares = ['allowNoAuth'];
+
+// With arguments
+export const middlewares = [{ name: 'shouldExist', args: ['projects'] }];
+
+// Direct import
+import isAdmin from 'middlewares/isAdmin';
+export const middlewares = [isAdmin];
+
+// Factory function
+import canEditProject from 'middlewares/canEditProject';
+export const middlewares = [canEditProject((ctx) => ctx.params.projectId)];
+
+// Inline
+export const middlewares = [
+  async (ctx, next) => {
+    // Custom logic
+    return next();
+  },
+];
+```
+
+## Global Middleware
+
+Create `/src/middlewares/global.js` to run on all endpoints:
+
+```javascript
+import isAuthorized from 'middlewares/isAuthorized';
+import attachRootProject from 'middlewares/attachRootProject';
+
+export default async (ctx, next) => {
+  await isAuthorized(ctx, async () => {
+    await attachRootProject(ctx, next);
+  });
+};
+```
+
+## Rules
+
+- Always call `next()` or throw
+- Use `runOrder` to control execution order
+- Factory functions for parameterized middlewares

package/starter/.cursor/skills/hive-overview/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: hive-overview
+description: Hive framework structure and conventions. Apply when working with this codebase.
+globs:
+  - src/**/*.js
+alwaysApply: false
+---
+
+# Hive Framework Overview
+
+Hive is a Koa-based Node.js framework with MongoDB, Zod validation, and auto-sync for embedded documents.
+
+## Directory Structure
+
+| Directory | Purpose | Edit? |
+|-----------|---------|-------|
+| `/.hive/` | Framework core | No - read only |
+| `/src/` | Application code | Yes |
+
+## Resources
+
+A resource is a feature module in `/src/resources/{name}/`:
+
+```
+src/resources/{name}/
+├── {name}.schema.js      # Required: DB schema
+├── endpoints/            # API routes
+├── handlers/             # Event listeners
+└── methods/              # Reusable functions
+```
+
+## Built-in (in .hive/)
+
+- `tokens` - Auth token storage
+- `users` - Base user schema  
+- `db` - Database layer with services
+
+## Key Imports
+
+```javascript
+import db from 'db';                    // Database
+import config from 'app-config';        // Config
+import { z } from 'zod';                // Validation
+```
+
+## Services Access
+
+```javascript
+const taskService = db.services.tasks;  // Auto-created from schema
+```

package/starter/.cursor/skills/hive-scheduler/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: hive-scheduler
+description: How to create scheduled jobs in Hive framework
+globs:
+  - src/scheduler/handlers/*.js
+alwaysApply: false
+---
+
+# Scheduler Jobs
+
+Background jobs on cron schedules.
+
+Location: `/src/scheduler/handlers/{jobName}.js`
+
+## Template
+
+```javascript
+import db from 'db';
+
+export const handler = async () => {
+  // Job logic
+};
+
+export const cron = '0 * * * *';  // Every hour
+```
+
+## Cron Patterns
+
+```
+┌─ minute (0-59)
+│ ┌─ hour (0-23)
+│ │ ┌─ day of month (1-31)
+│ │ │ ┌─ month (1-12)
+│ │ │ │ ┌─ day of week (0-6)
+* * * * *
+```
+
+| Pattern | Schedule |
+|---------|----------|
+| `* * * * *` | Every minute |
+| `*/5 * * * *` | Every 5 minutes |
+| `0 * * * *` | Every hour |
+| `0 */12 * * *` | Every 12 hours |
+| `0 0 * * *` | Daily at midnight |
+| `0 9 * * 1` | Mondays at 9am |
+
+## Examples
+
+**Sync external data:**
+```javascript
+import db from 'db';
+import moment from 'moment';
+import externalApi from 'services/externalApi';
+
+export const handler = async () => {
+  const items = await externalApi.list({
+    updatedSince: moment().subtract(5, 'minutes').toDate(),
+  });
+  
+  for (const item of items) {
+    await db.services.items.updateOne(
+      { externalId: item.id },
+      (doc) => ({ ...doc, ...item })
+    );
+  }
+};
+
+export const cron = '*/5 * * * *';
+```
+
+**Mark overdue:**
+```javascript
+import db from 'db';
+import moment from 'moment';
+
+export const handler = async () => {
+  await db.services.invoices.updateMany(
+    {
+      isPaid: { $ne: true },
+      isDue: { $ne: true },
+      dueOn: { $lt: new Date() },
+    },
+    (doc) => ({ ...doc, isDue: true })
+  );
+};
+
+export const cron = '0 */12 * * *';
+```
+
+## Rules
+
+- Export both `handler` and `cron`
+- Keep jobs idempotent (safe to re-run)
+- Log progress for debugging

package/starter/.cursor/skills/hive-schema/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: hive-schema
+description: How to create database schemas in Hive framework
+globs:
+  - src/resources/**/*.schema.js
+alwaysApply: false
+---
+
+# Creating Database Schemas
+
+Location: `/src/resources/{name}/{name}.schema.js`
+
+## Template
+
+```javascript
+import { z } from 'zod';
+import dbSchema from 'helpers/schema/db.schema.js';
+
+const schema = dbSchema.extend({
+  // Fields here
+});
+
+export default schema;
+
+export const secureFields = []; // Hidden from API responses
+```
+
+## Field Patterns
+
+**Simple fields:**
+```javascript
+title: z.coerce.string().nullable().optional(),
+count: z.coerce.number().nullable().optional(),
+isActive: z.coerce.boolean().nullable().optional(),
+dueOn: z.coerce.date().nullable().optional(),
+```
+
+**Reference to another document:**
+```javascript
+user: z
+  .object({
+    _id: z.string(),
+    fullName: z.coerce.string().nullable().optional(),
+    avatarUrl: z.coerce.string().nullable().optional(),
+  })
+  .nullable()
+  .optional(),
+```
+
+**Array of references:**
+```javascript
+managers: z
+  .array(
+    z.object({
+      _id: z.string(),
+      fullName: z.coerce.string().nullable().optional(),
+    }).nullable().optional(),
+  )
+  .nullable()
+  .optional(),
+```
+
+**Flexible object:**
+```javascript
+data: z.object({}).passthrough().nullable().optional(),
+```
+
+## Rules
+
+- Always use `z.coerce` for type safety
+- Always add `.nullable().optional()` unless required
+- Include fields you need in references (for auto-sync)
+- Add sensitive fields to `secureFields` array