@paralect/hive 0.1.49 → 0.1.50-alpha.0

package/test-app/.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/test-app/.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/test-app/.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/test-app/.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/test-app/.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/test-app/.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

package/test-app/.cursor/skills/hive-service/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: hive-service
+description: How to create external services in Hive framework
+globs:
+  - src/services/*.js
+alwaysApply: false
+---
+
+# Services
+
+Services wrap external APIs and utilities.
+
+Location: `/src/services/{name}.js`
+
+## API Client Template
+
+```javascript
+import config from 'app-config';
+import axios from 'axios';
+
+const client = axios.create({
+  baseURL: 'https://api.example.com',
+  headers: {
+    Authorization: `Bearer ${config.example.apiKey}`,
+  },
+});
+
+export default {
+  getItems: async (params) => {
+    const response = await client.get('/items', { params });
+    return response.data;
+  },
+  
+  createItem: async (data) => {
+    const response = await client.post('/items', data);
+    return response.data;
+  },
+};
+```
+
+## SDK Wrapper Template
+
+```javascript
+import config from 'app-config';
+import { WebClient } from '@slack/web-api';
+
+const client = new WebClient(config.slack.botToken);
+
+export default {
+  client,
+  
+  postMessage: async ({ channel, text }) => {
+    return client.chat.postMessage({ channel, text });
+  },
+};
+```
+
+## Utility Service Template
+
+```javascript
+import _ from 'lodash';
+
+export const when = (condition, result, elseResult = {}) => {
+  if (_.isUndefined(condition)) return {};
+  if (!condition) return elseResult;
+  return _.isFunction(result) ? result() : result;
+};
+
+export const base64 = {
+  encode: (obj) => Buffer.from(JSON.stringify(obj)).toString('base64'),
+  decode: (str) => JSON.parse(Buffer.from(str, 'base64').toString()),
+};
+```
+
+## Using Services
+
+```javascript
+import harvest from 'services/harvest';
+import slackService from 'services/slack';
+import { when } from 'services/utils';
+
+// API calls
+const invoices = await harvest.getInvoices({ projectId });
+
+// SDK usage
+await slackService.postMessage({ channel: '#general', text: 'Hello' });
+
+// Utilities
+const query = { ...when(status, { status }) };
+```