|
| 1 | +--- |
| 2 | +title: 'Services' |
| 3 | +navigation: |
| 4 | + icon: i-lucide-share-2 |
| 5 | +description: 'Lookup tables for ctx.services: the DevframeServicesHost methods, the wire-service definition and descriptor fields, the advertised meta shape, and the first-party built-in services.' |
| 6 | +--- |
| 7 | + |
| 8 | +Lookup tables for `ctx.services`, the cross-devframe capability registry. Each section links the [Cross-Devframe Services](/guide/services) guide that teaches it. |
| 9 | + |
| 10 | +## `DevframeServicesHost` |
| 11 | + |
| 12 | +The methods on `ctx.services` — [Cross-Devframe Services](/guide/services#the-devframeserviceshost-api). |
| 13 | + |
| 14 | +| Method | Signature | Role | |
| 15 | +|--------|-----------|------| |
| 16 | +| `provide` | `(id, service) => revoke` | Publish an in-process service under a namespaced id. Throws [`DF0037`](/errors/DF0037) if the id is taken. | |
| 17 | +| `get` | `(id) => service \| undefined` | The service currently provided under `id` (augmented type, else `unknown`). | |
| 18 | +| `has` | `(id) => boolean` | Whether a service is provided under `id`. | |
| 19 | +| `whenAvailable` | `(id, cb) => unsubscribe` | Run `cb` as soon as the service exists — now if provided, else on `provide` — and re-fire on revoke/re-provide. | |
| 20 | +| `keys` | `() => string[]` | Ids of every currently-provided service. | |
| 21 | +| `install` | `(input, options?) => Promise<api \| undefined>` | Install a [wire service](#wire-service-definition-fields) at runtime (the dynamic escape hatch; the common path is declarative). `options.resolveFrom` is the descriptor's resolution base. | |
| 22 | +| `ready` | `() => Promise<void>` | **Internal.** Construct every queued wire service before any `setup` runs. Adapters call it; application code uses declarative `services`. | |
| 23 | + |
| 24 | +## Service tiers |
| 25 | + |
| 26 | +The two tiers a service can take — [Cross-Devframe Services](/guide/services). |
| 27 | + |
| 28 | +| Tier | Shared how | Registers RPC | Advertised to clients | |
| 29 | +|------|-----------|---------------|-----------------------| |
| 30 | +| In-process service (`provide`/`get`) | live object, node side only | No | No | |
| 31 | +| [Wire service](/guide/services#wire-services) (`install` / declarative `services`) | npm package, node API + RPC | Yes, under its `scope` | Yes, via `devframe:services` shared state | |
| 32 | + |
| 33 | +## Wire-service definition fields |
| 34 | + |
| 35 | +The fields of a `DevframeServiceDefinition` returned by a service package's `create<X>Service` factory — [Shipping a wire service](/guide/services#shipping-one). |
| 36 | + |
| 37 | +| Field | Type | Description | |
| 38 | +|-------|------|-------------| |
| 39 | +| `package` | `string` | **Required.** npm package name — also its registry key (`ctx.services.has(pkg)`). | |
| 40 | +| `version` | `string` | **Required.** Semver; advertised to clients, checked against declared ranges. | |
| 41 | +| `scope` | `string` | **Required.** RPC namespace its functions register under (e.g. `devframes:service:open`); `setup` gets a context pre-scoped to it. | |
| 42 | +| `meta` | `Record<string, unknown>` | Extra advertised metadata (feature flags, defaults). Must be JSON-serializable. | |
| 43 | +| `options` | `Options` | This instance's own option set, baked in by its factory; joins the merge. | |
| 44 | +| `mergeOptions` | `(sets: Options[]) => Options` | Merge multiple installers' option sets. Default: shallow, later wins. | |
| 45 | +| `setup` | `(ctx, info) => api` | **Required.** Register RPC on the pre-scoped context; return the node API served from `ctx.services.get(package)`. | |
| 46 | + |
| 47 | +## Wire-service descriptor fields |
| 48 | + |
| 49 | +The declarative reference form on `DevframeDefinition.services` / `initHub({ services })` — [Declaring services](/guide/services#declaring). |
| 50 | + |
| 51 | +| Field | Type | Description | |
| 52 | +|-------|------|-------------| |
| 53 | +| `package` | `string` | **Required.** npm package name; its default export is the factory the host imports. | |
| 54 | +| `version` | `string` | Accepted semver range. Unsatisfied warns ([`DF0069`](/errors/DF0069)), or throws ([`DF0068`](/errors/DF0068)) when `required`. | |
| 55 | +| `required` | `boolean` | Fail hard on a missing package ([`DF0067`](/errors/DF0067)) or unsatisfied range. Default `false` — a missing service is skipped and clients see `has() === false`. | |
| 56 | +| `options` | `Options` | Option set this installer contributes to the merge. | |
| 57 | + |
| 58 | +## Advertised service meta |
| 59 | + |
| 60 | +Each installed service's entry in the `devframe:services` [shared state](/guide/shared-state), mirrored to RPC clients as `rpc.services` — [Feature-detecting on the RPC client](/guide/services#feature-detecting-on-the-rpc-client). |
| 61 | + |
| 62 | +| Field | Description | |
| 63 | +|-------|-------------| |
| 64 | +| `package` | npm package name — the registry key. | |
| 65 | +| `version` | Installed version of the service. | |
| 66 | +| `scope` | RPC namespace its functions live under. | |
| 67 | +| `meta` | Extra service-declared metadata. | |
| 68 | + |
| 69 | +## Built-in services |
| 70 | + |
| 71 | +The first-party wire services (`@devframes/service-*`), each installed once per host and consumed by any devframe or RPC client — [Built-in services](/guide/services#built-in-services). |
| 72 | + |
| 73 | +| Package | Scope | RPC functions | Options | |
| 74 | +|---------|-------|---------------|---------| |
| 75 | +| `@devframes/service-open` | `devframes:service:open` | `open-in-editor`, `open-in-finder` | `{ editor?, roots? }` — later wins; `roots` union-merged. Refuses paths outside the workspace root plus `roots`, gates editors to `KNOWN_EDITORS`. | |
| 76 | +| `@devframes/service-git` | `devframes:service:git` | `status`, `log`, `show`, `readFile`, `diff`, `branches`, `tags`, `stage`, `unstage`, `commit` | `{ cwd? }` — one repo fixed at install. Write ops are exposed; authorization is the host framework's boundary. | |
| 77 | +| `@devframes/service-shiki` | `devframes:service:shiki` | `highlight`, `code-to-hast`, `code-to-tokens` | `{ themes?, langs? }` — light/dark pair (defaults `vitesse-light`/`vitesse-dark`, later wins) and preloaded languages (union-merged). Queries are client-`cacheable`, LRU-cached per `(code, lang, themes)`. | |
0 commit comments