@live-change/frontend-template 0.9.199 → 0.9.201

package/.claude/skills/live-change-backend-change-triggers/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: live-change-backend-change-triggers
+description: React to model changes with automatic change triggers from the relations plugin
+---
+
+# Skill: live-change-backend-change-triggers (Claude Code)
+
+Use this skill when you need to **react to model changes** — run logic when a record is created, updated, or deleted.
+
+## When to use
+
+- You need to keep derived data in sync when a model changes (e.g. create/cancel a timer when a schedule is created/updated/deleted).
+- You want to initialize related resources when a model is created.
+- You need cross-service reactions to model lifecycle events.
+- You want custom cleanup logic on delete.
+
+## How it works
+
+The relations plugin automatically fires change triggers for every model that uses relations (`propertyOf`, `itemOf`, `userItem`, `propertyOfAny`, etc.). You just define a trigger with the matching name.
+
+## Step 1 – Understand the naming convention
+
+For a model `MyModel` in service `myService`, these triggers are fired automatically:
+
+| Trigger name | When |
+|---|---|
+| `createMyService_MyModel` | On create |
+| `updateMyService_MyModel` | On update |
+| `deleteMyService_MyModel` | On delete |
+| `changeMyService_MyModel` | On any change |
+| `createObject` / `updateObject` / `deleteObject` / `changeObject` | Generic (all models) |
+
+The pattern is: `{changeType}{ServiceName}_{ModelName}` where service name is capitalized.
+
+## Step 2 – Define a change trigger (recommended: use `change*`)
+
+The `change*` variant covers all cases. Check `data` and `oldData` to distinguish create/update/delete:
+
+```javascript
+definition.trigger({
+  name: 'changeMyService_MyModel',
+  properties: {
+    object: {
+      type: MyModel,
+      validation: ['nonEmpty'],
+    },
+    data: {
+      type: Object,
+    },
+    oldData: {
+      type: Object,
+    }
+  },
+  async execute({ object, data, oldData }, { service, trigger, triggerService }, emit) {
+    if(oldData) {
+      // Updated or deleted — clean up old state
+    }
+    if(data) {
+      // Created or updated — set up new state
+    }
+  }
+})
+```
+
+How to distinguish:
+
+| `oldData` | `data` | Meaning |
+|---|---|---|
+| `null` | `{...}` | Created |
+| `{...}` | `{...}` | Updated |
+| `{...}` | `null` | Deleted |
+
+## Step 3 – Real example: cron-service reacting to Schedule changes
+
+The cron-service uses `changeCron_Schedule` to automatically manage timers when schedules are created, updated, or deleted:
+
+```javascript
+// Source: live-change-stack/services/cron-service/schedule.js
+
+definition.trigger({
+  name: 'changeCron_Schedule',
+  properties: {
+    object: {
+      type: Schedule,
+      validation: ['nonEmpty'],
+    },
+    data: {
+      type: Object,
+    },
+    oldData: {
+      type: Object,
+    }
+  },
+  execute: async ({ object, data, oldData }, { service, trigger, triggerService }, emit) => {
+    if(oldData) {
+      // Cancel old timer on update or delete
+      await triggerService({
+        service: 'timer',
+        type: 'cancelTimerIfExists',
+      }, {
+        timer: 'cron_Schedule_' + object
+      })
+      await ScheduleInfo.delete(object)
+    }
+    if(data) {
+      // Create new timer on create or update
+      await processSchedule({ id: object, ...data }, { triggerService })
+    }
+  }
+})
+```
+
+This means: when a user creates a Schedule via the UI or API, the timer is automatically set up. When they update it, the old timer is canceled and a new one created. When they delete it, the timer is canceled.
+
+## Step 4 – Specific lifecycle triggers (alternative)
+
+If you only care about one lifecycle event, use the specific variant:
+
+```javascript
+// React only to creation
+definition.trigger({
+  name: 'createBilling_Billing',
+  properties: {
+    object: { type: Billing }
+  },
+  async execute({ object }, { triggerService }, emit) {
+    // Initialize balance when billing is created
+    const existingBalance = await app.serviceViewGet('balance', 'balance', {
+      ownerType: 'billing_Billing', owner: object
+    })
+    if(!existingBalance) {
+      await triggerService({
+        service: 'balance',
+        type: 'balance_setOrUpdateBalance',
+      }, { ownerType: 'billing_Billing', owner: object })
+    }
+  }
+})
+```
+
+## Step 5 – Full trigger parameters
+
+All change triggers receive:
+
+```javascript
+{
+  objectType,   // e.g. 'cron_Schedule' (service_Model)
+  object,       // record ID
+  identifiers,  // parent identifiers from the model's relations
+  data,         // new data (null on delete)
+  oldData,      // old data (null on create)
+  changeType    // 'create', 'update', or 'delete'
+}
+```
+
+The `identifiers` object contains the parent references defined in the model's relations (e.g. for `itemOf: { what: Device }`, identifiers would include `{ device: '...' }`).
+
+## Step 6 – Cross-service triggers
+
+Change triggers work across services. Define the trigger in any service — the framework routes it by name:
+
+```javascript
+// In serviceA, react to changes in serviceB's Model
+const SomeModel = definition.foreignModel('serviceB', 'SomeModel')
+
+definition.trigger({
+  name: 'changeServiceB_SomeModel',
+  properties: {
+    object: { type: SomeModel },
+    data: { type: Object },
+    oldData: { type: Object }
+  },
+  async execute({ object, data, oldData }, { triggerService }) {
+    // React to changes in SomeModel from serviceB
+  }
+})
+```
+
+## Common patterns
+
+| Pattern | Trigger to use | Example |
+|---|---|---|
+| Keep derived data in sync | `changeSvc_Model` | Cron: cancel/create timers on schedule change |
+| Initialize on creation | `createSvc_Model` | Billing: create balance when billing created |
+| Custom cleanup on delete | `deleteSvc_Model` | Custom: archive or notify before deletion |
+| React to any model change | `changeObject` | Audit: log all changes across all models |

package/.claude/skills/live-change-design-actions-views-triggers/SKILL.md

@@ -0,0 +1,462 @@
+---
+name: live-change-design-actions-views-triggers
+description: Design actions, views, triggers with indexes and batch processing patterns
+---
+
+# Skill: live-change-design-actions-views-triggers (Claude Code)
+
+Use this skill to design **actions, views, and triggers** in LiveChange services while making good use of indexes and avoiding full-table scans.
+
+## When to use
+
+- You add or change actions on existing models.
+- You define new views (especially list/range views).
+- You implement triggers (online/offline, batch processing, async result flows).
+
+## Step 1 – Design an action
+
+1. **Clarify the goal**:
+   - create / update / delete a record,
+   - or create a “command” that will be completed later.
+2. **Define `properties`** clearly:
+   - only include what the client must provide,
+   - fetch the rest from the database via indexes.
+3. **Use indexes**, not full scans:
+   - `indexObjectGet('bySomething', { ... })` for single-object lookups,
+   - `indexRangeGet('bySomething', { ... })` for lists.
+4. **Return a useful result**:
+   - new object id,
+   - session keys,
+   - any data needed for the next step.
+
+Example:
+
+```js
+definition.action({
+  name: 'someAction',
+  properties: {
+    someKey: { type: String }
+  },
+  async execute({ someKey }, { client, service }) {
+    const obj = await SomeModel.indexObjectGet('bySomeKey', { someKey })
+    if(!obj) throw new Error('notFound')
+
+    const id = app.generateUid()
+
+    await SomeOtherModel.create({
+      id
+      // ...
+    })
+
+    return { id }
+  }
+})
+```
+
+## Step 2 – Design a view
+
+1. Decide what kind of data source you have, then pick the **view variant** (exactly one):
+
+| Variant | When to use |
+| --- | --- |
+| `daoPath` | Data is stored in the framework DAO (preferred). The framework auto-generates both `get` and `observable` from `daoPath`. |
+| `get` + `observable` | External or custom reactive data source (eg. WebSocket client, RPC stream). **Both are required together.** |
+| `fetch` | Remote, non-reactive request/response data (eg. GeoIP). Often paired with `remote: true`. |
+
+2. Decide if you need:
+   - a **single** object view, or
+   - a **list/range** view.
+3. Define `properties` for the view:
+   - only parameters needed for filtering,
+   - types consistent with model fields.
+4. Prefer `daoPath` when you are reading from the DAO:
+   - use model paths (`Model.path`, `Model.rangePath`, `Model.sortedIndexRangePath`, `Model.indexObjectPath`)
+   - use `...App.rangeProperties` + `App.extractRange(props)` for range views
+
+### Example: `daoPath` (preferred, DAO-backed)
+
+```js
+definition.view({
+  name: 'costInvoice',
+  properties: {
+    costInvoice: {
+      type: String
+    }
+  },
+  returns: { type: Object },
+  async daoPath({ costInvoice }) {
+    return CostInvoice.path(costInvoice)
+  }
+})
+```
+
+### Example: `get` + `observable` together (external / reactive)
+
+```js
+definition.view({
+  name: 'session',
+  properties: {},
+  returns: { type: Number },
+  async get(params, { client }) {
+    return onlineClient.get(['online', 'session', { ...params, session: client.session }])
+  },
+  async observable(params, { client }) {
+    return onlineClient.observable(
+      ['online', 'session', { ...params, session: client.session }],
+      ReactiveDao.ObservableValue
+    )
+  }
+})
+```
+
+### Example: `fetch` (remote / non-reactive)
+
+```js
+definition.view({
+  name: 'myCountry',
+  properties: {},
+  returns: { type: String },
+  remote: true,
+  async fetch(props, { client }) {
+    return await getGeoIp(client.ip)
+  }
+})
+```
+
+### Anti-pattern: `get` without `observable` (do not do this)
+
+```js
+definition.view({
+  name: 'brokenView',
+  properties: {
+    id: { type: String }
+  },
+  returns: { type: Object },
+  async get({ id }) {
+    return await SomeModel.get(id)
+  }
+})
+```
+
+## Step 3 – Online/offline triggers
+
+1. Identify events:
+   - session or connection goes online,
+   - session or connection goes offline.
+2. Define triggers with minimal `properties` (usually just an id).
+3. Update only the necessary fields (`status`, `lastSeenAt`, etc.).
+
+Example:
+
+```js
+definition.trigger({
+  name: 'sessionConnectionOnline',
+  properties: {
+    connection: { type: String }
+  },
+  async execute({ connection }, { service }) {
+    await Connection.update(connection, {
+      status: 'online',
+      lastSeenAt: new Date()
+    })
+  }
+})
+
+definition.trigger({
+  name: 'sessionConnectionOffline',
+  properties: {
+    connection: { type: String }
+  },
+  async execute({ connection }, { service }) {
+    await Connection.update(connection, {
+      status: 'offline'
+    })
+  }
+})
+```
+
+## Step 4 – Batch triggers (avoid full scans)
+
+1. Pick a **batch size** (e.g. 32 or 128).
+2. Use `rangeGet` with `gt: lastId` in a loop:
+   - start with `last = ''`,
+   - after each batch, set `last` to the last record’s id,
+   - stop when the batch is empty.
+
+Example:
+
+```js
+definition.trigger({
+  name: 'allOffline',
+  async execute({}, { service }) {
+    let last = ''
+    while(true) {
+      const items = await Connection.rangeGet({
+        gt: last,
+        limit: 32
+      })
+      if(items.length === 0) break
+
+      for(const item of items) {
+        await Connection.update(item.id, { status: 'offline' })
+      }
+
+      last = items[items.length - 1].id
+    }
+  }
+})
+```
+
+## Step 5 – Grant access on entity creation
+
+When a model uses `entity` with `writeAccessControl` / `readAccessControl`, the auto-generated CRUD checks roles but does **not** grant them. Add a change trigger to grant the creator `'owner'` after creation:
+
+```js
+definition.trigger({
+  name: 'changeMyService_MyModel',
+  properties: {
+    object: { type: MyModel, validation: ['nonEmpty'] },
+    data: { type: Object },
+    oldData: { type: Object }
+  },
+  async execute({ object, data, oldData }, { client, triggerService }) {
+    if(!data || oldData) return   // only on create (data present, no oldData)
+    if(!client?.user) return
+
+    await triggerService({ service: 'accessControl', type: 'accessControl_setAccess' }, {
+      objectType: 'myService_MyModel',   // format: serviceName_ModelName
+      object,
+      roles: ['owner'],
+      sessionOrUserType: 'user_User',
+      sessionOrUser: client.user,
+      lastUpdate: new Date()
+    })
+  }
+})
+```
+
+For publicly accessible objects, also call `accessControl_setPublicAccess`:
+
+```js
+await triggerService({ service: 'accessControl', type: 'accessControl_setPublicAccess' }, {
+  objectType: 'myService_MyModel',
+  object,
+  userRoles: ['reader'],       // roles for all logged-in users
+  sessionRoles: ['reader'],    // roles for all sessions (including anonymous)
+  lastUpdate: new Date()
+})
+```
+
+Key points:
+- `objectType` format: `serviceName_ModelName` (e.g. `company_Company`, `uploadedFiles_File`)
+- `sessionOrUserType`: `'user_User'` for logged-in users, `'session_Session'` for anonymous
+- For anonymous users: `sessionOrUser: client.session`
+- Use `Promise.all([...])` when setting both public and per-user access
+
+## Step 6 – Pending + resolve pattern for async results
+
+Use this pattern when an action initiates a command that will be completed by an external process (device, worker, etc.) and you want the action to wait with a timeout.
+
+### Steps
+
+1. Implement a helper module with an in-memory `Map`:
+   - `waitForCommand(id, timeoutMs)` – returns a Promise,
+   - `resolveCommand(id, result)` – resolves and clears timeout.
+2. In the main action:
+   - create a record with `status: 'pending'`,
+   - call `waitForCommand(id, timeoutMs)` and `return` the result.
+3. In the reporting action:
+   - update the record (`status: 'completed'`, `result`),
+   - call `resolveCommand(id, result)`.
+
+Helper sketch:
+
+```js
+const pendingCommands = new Map()
+
+export function waitForCommand(commandId, timeoutMs = 115000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingCommands.delete(commandId)
+      reject(new Error('timeout'))
+    }, timeoutMs)
+    pendingCommands.set(commandId, { resolve, reject, timer })
+  })
+}
+
+export function resolveCommand(commandId, result) {
+  const pending = pendingCommands.get(commandId)
+  if(pending) {
+    clearTimeout(pending.timer)
+    pendingCommands.delete(commandId)
+    pending.resolve(result)
+  }
+}
+```
+
+## Step 7 – Enable access-control indexes for accessible objects
+
+When you need **global listings of objects accessible to a user** (not limited to direct `userItem` relations), enable the indexed access-control pipeline and use the specialized views it exposes.
+
+### 7.1 Enable `indexed: true` in app config
+
+In the app server config, set `indexed: true` on the access-control service:
+
+```js
+// app.server/app.config.js
+{
+  name: 'accessControl',
+  createSessionOnUpdate: true,
+  contactTypes,
+  indexed: true
+}
+```
+
+This activates the index pipeline and views defined in `services/access-control-service/indexes.js`.
+
+### 7.2 Index pipeline overview
+
+When `indexed: true` is enabled, the following indexes are created:
+
+1. `childByParent` – objects by parent (`parentType`, `parent`, `childType`, `child`, `property`)
+2. `parentByChild` – parents by child (reverse of `childByParent`)
+3. `pathsByAncestorDescendantRelation` – all ancestor/descendant paths in the object tree
+4. `expandedRoles` – propagates roles assigned on ancestors down to all descendants
+5. `roleByOwnerAndObject` – deduplicated roles per `(sessionOrUser, object, role)`
+6. `objectByOwnerAndRole` – objects by `(sessionOrUser, role, objectType, object)`
+7. `ownerByObjectAndRole` – owners by `(objectType, object, role, sessionOrUser)`
+
+These are maintained automatically based on:
+
+- `Access` records (per-user roles),
+- `PublicAccess` records (public roles),
+- parent relations registered via the relations plugin.
+
+### 7.3 Self-service views (current user)
+
+The following views do **not** need explicit `sessionOrUser` parameters – they infer the current user or session from `client`:
+
+- `myAccessibleObjects({ objectType?, ...range })`
+- `myAccessibleObjectsCount({ objectType?, ...range })`
+- `myAccessibleObjectsByRole({ role, objectType?, ...range })`
+- `myAccessibleObjectsByRoleCount({ role, objectType?, ...range })`
+
+Use them for:
+
+- “all companies I can access” (`objectType: 'company_Company'`),
+- “all projects where I am owner” (`role: 'owner'`, `objectType: 'project_Project'`),
+- dashboards listing entities across services.
+
+On the frontend, the typical pattern is:
+
+```js
+const accessibleObjectsPath = computed(() =>
+  client.value.user
+    ? path.accessControl.myAccessibleObjects({
+        objectType: 'myService_MyModel'
+      }).with(accessible =>
+        path.myService.myModel({ myModel: accessible.object }).bind('entity')
+      )
+    : null
+)
+```
+
+### 7.4 Admin views (explicit user / session)
+
+For administrative tools you can use:
+
+- `accessibleObjects({ sessionOrUserType, sessionOrUser, objectType?, ...range })`
+- `accessibleObjectsCount(...)`
+- `accessibleObjectsByRole({ sessionOrUserType, sessionOrUser, role, objectType?, ...range })`
+- `accessibleObjectsByRoleCount(...)`
+- `objectAccesses({ objectType, object, role?, ...range })`
+- `objectAccessesCount(...)`
+
+These views:
+
+- require the caller to have `admin` role (checked in access-control service),
+- allow you to inspect which objects a user can access, and who can access a given object.
+
+Example DAO path for a list view:
+
+```js
+definition.view({
+  name: 'userProjectAccesses',
+  properties: {
+    user: { type: String }
+  },
+  daoPath({ user }, { client, service }) {
+    if(!client.roles.includes('admin')) throw new Error('forbidden')
+    const range = App.extractRange({})
+    return accessibleObjectsByRoleIndex.rangePath(
+      ['user_User', user, 'member', 'project_Project'],
+      range
+    )
+  }
+})
+```
+
+### 7.5 Non-indexed views that are always available
+
+Even without `indexed: true`, `services/access-control-service/view.js` defines views that work on the raw `Access` and invitation tables:
+
+- `myAccessesByObjectType({ objectType, ...range })`
+- `myAccessesByObjectTypeAndRole({ objectType, role, ...range })`
+- `myAccessInvitationsByObjectType({ objectType, ...range })`
+- `myAccessInvitationsByObjectTypeAndRole({ objectType, role, ...range })`
+
+Use them when:
+
+- you do not want to enable the full indexed pipeline yet,
+- you mostly need **per-type** lists, not cross-type queries,
+- you are building invitation lists or paginated access-based lists (`RangeViewer`).
+
+These views are the backend counterparts of the frontend patterns described in `live-change-frontend-accessible-objects`.
+
+Remember:
+
+- `objectType` format is always `serviceName_ModelName`,
+- for anonymous users use `sessionOrUserType: 'session_Session'` and `sessionOrUser: client.session`,
+- enable `indexed: true` when you need efficient “all my objects” listings and admin inspection tools across large datasets.
+```
+## Step 6 – Pending + resolve pattern for async results
+
+Use this pattern when an action initiates a command that will be completed by an external process (device, worker, etc.) and you want the action to wait with a timeout.
+
+### Steps
+
+1. Implement a helper module with an in-memory `Map`:
+   - `waitForCommand(id, timeoutMs)` – returns a Promise,
+   - `resolveCommand(id, result)` – resolves and clears timeout.
+2. In the main action:
+   - create a record with `status: 'pending'`,
+   - call `waitForCommand(id, timeoutMs)` and `return` the result.
+3. In the reporting action:
+   - update the record (`status: 'completed'`, `result`),
+   - call `resolveCommand(id, result)`.
+
+Helper sketch:
+
+```js
+const pendingCommands = new Map()
+
+export function waitForCommand(commandId, timeoutMs = 115000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingCommands.delete(commandId)
+      reject(new Error('timeout'))
+    }, timeoutMs)
+    pendingCommands.set(commandId, { resolve, reject, timer })
+  })
+}
+
+export function resolveCommand(commandId, result) {
+  const pending = pendingCommands.get(commandId)
+  if(pending) {
+    clearTimeout(pending.timer)
+    pendingCommands.delete(commandId)
+    pending.resolve(result)
+  }
+}
+```
+