Yatoi

https://github.com/yatoi-dev/yatoi-js
Admin
Plugin kernel with reversible effects, typed service discovery and cascade unload, with React and...
Tokens:47,723
Snippets:376
Trust Score:0.7
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Never mutate the kernel during render: kernel.load/unload and scope.provide/contribute belong in event handlers, effects, or bootstrap.
- Tokens are imported symbols from one contract module, never string literals at call sites.
- Prefer <Requires of={[Token]}> over useService(Token)! so removal unmounts the dependent subtree.
- After an await inside setup, check scope.active before provide or contribute.

================
CODE SNIPPETS
================
### Run example todo app

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/README.md

Start the example todo app in development mode. See the example's README for details.

```bash
pnpm --filter yatoi-example-todo dev
```

--------------------------------

### Install kernel app-wide with app.use(yatoi, { kernel })

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Registers the kernel for the entire Vue app. Prefer this over provideKernel in a component's setup() because Vue's provide() doesn't reach the providing instance itself.

```ts
import { createApp } from 'vue'
import { yatoi } from '@yatoi/vue'
import { kernel } from './kernel'
import App from './App.vue'

createApp(App).use(yatoi, { kernel }).mount('#app')
```

--------------------------------

### Install @yatoi/kernel and @yatoi/slots

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/packages/slots/README.md

Install the required packages using npm.

```bash
npm i @yatoi/kernel @yatoi/slots
```

--------------------------------

### Define a plugin with inject and provides

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/concepts.md

Defines a plugin named 'sync' that activates only when Clock and Storage are present, provides SyncStatus, and uses the scope to get injected services, defer cleanup, and provide a service. The setup function is typed and the plugin is plain data until loaded by a kernel.

```ts
const syncPlugin = definePlugin({
  name: 'sync',
  inject: [Clock, Storage],   // activates only when both are present
  provides: [SyncStatus],     // may provide only what it declares
  setup(scope) {
    const clock = scope.get(Clock)        // typed non-null: it's injected
    scope.defer(subscribe(clock))         // reversible effect
    scope.provide(SyncStatus, status)     // published; removed on dispose
  },
})
```

--------------------------------

### Install @yatoi/vue and vue

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/packages/vue/README.md

Install the package and its peer dependency using npm.

```bash
npm i @yatoi/vue vue
```

--------------------------------

### Run preflight checks

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/releasing.md

Run the complete preflight before publishing: frozen-lockfile install, tests, typecheck, and pack:check. pack:check fails if a tarball contains source maps, TypeScript build metadata, tests, examples, or unresolved workspace: dependencies.

```bash
pnpm install --frozen-lockfile
pnpm test
pnpm typecheck
pnpm pack:check
```

--------------------------------

### Provide a nested kernel with provideKernel

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Use provideKernel in a component's setup() to provide a different kernel to a subtree. This is the right tool for a nested or scoped kernel, unlike the app-wide installation.

```ts
import { provideKernel } from '@yatoi/vue'

export default defineComponent({
  setup() {
    provideKernel(nestedKernel)
    // ...
  },
})
```

--------------------------------

### Install @yatoi/kernel via npm

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/packages/kernel/README.md

Install the package using npm.

```bash
npm i @yatoi/kernel
```

--------------------------------

### Setup @yatoi/vue with createApp

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/packages/vue/README.md

Create a Vue app with a kernel, define a service and plugin, and use the yatoi plugin with the kernel.

```ts
import { createApp, defineComponent, h } from 'vue'
import { createKernel, definePlugin, defineService } from '@yatoi/kernel'
import { Requires, yatoi } from '@yatoi/vue'
import { Slot } from '@yatoi/vue/slots'
declare module '@yatoi/slots' { interface Slots { 'sidebar.item': Record<never, never> } }
const Clock = defineService<{ now(): number }>('clock')
const clock = definePlugin({ name: 'clock', provides: [Clock], setup(scope) {
  scope.provide(Clock, { now: () => Date.now() })
  scope.defer(() => console.log('clock stopped'))
} })
const kernel = createKernel()
kernel.load(clock)
const App = defineComponent(() => () => h(Requires, { of: [Clock] }, {
  default: ([value]) => [h('time', value.now()), h(Slot, { name: 'sidebar.item' })],
}))
createApp(App).use(yatoi, { kernel }).mount('#app')
```

--------------------------------

### Install @yatoi/react

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/packages/react/README.md

Install the React bindings package along with React and React DOM. Requires React 18 or 19.

```bash
npm i @yatoi/react react react-dom
```

--------------------------------

### Async setup with scope.active check (TypeScript)

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Use this pattern when setup is async. After awaiting, check scope.active before performing side effects. If the scope is inactive, close the socket and return to avoid leaks. Defer cleanup before the await when possible.

```TypeScript
async setup(scope) {
  const socket = await connect()
  if (!scope.active) { socket.close(); return }   // deps vanished mid-await
  scope.defer(() => socket.close())
  scope.provide(Socket, socket)
}
```

--------------------------------

### Install dependencies with pnpm

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/README.md

Install all project dependencies using pnpm. Requires Node ≥ 22.22.2 and pnpm 9.

```bash
pnpm install
```

--------------------------------

### Install @yatoi/vue dependencies with pnpm

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Install the kernel, Vue binding, and Vue itself. Required before using any @yatoi/vue features.

```bash
pnpm add @yatoi/kernel @yatoi/vue vue
```

--------------------------------

### Install Yatoi packages with pnpm

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Install the core Yatoi packages and React dependencies. @yatoi/kernel has no dependencies, @yatoi/slots depends only on @yatoi/kernel, and @yatoi/react peer-depends on react ^18 || ^19.

```bash
pnpm add @yatoi/kernel @yatoi/react react react-dom
```

--------------------------------

### Register and unload plugins with kernel.load and kernel.unload

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/concepts.md

Shows the derived activation and cascade unload behavior. A plugin runs setup when all its inject tokens are present and disposes when any goes away. Load order does not matter; unloading a thread disposes dependents in reverse dependency order, and reloading re-runs setup with a fresh scope.

```javascript
kernel.load(syncPlugin)    // registered, inactive — Clock isn't there yet
kernel.load(clockPlugin)   // clock activates; sync activates right after
kernel.unload(clockPlugin) // sync disposes first, then clock
kernel.load(clockPlugin)   // both come back, sync with a fresh scope
```

--------------------------------

### Declare and use a slot with @yatoi/slots

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/packages/slots/README.md

Shows how to declare a slot type, contribute to it in a plugin, and list contributions. The example declares a 'task.badge' slot with a taskId property, contributes a badge renderer, and logs the number of contributions.

```ts
import { createKernel, definePlugin } from '@yatoi/kernel'
import { slot } from '@yatoi/slots'
declare module '@yatoi/slots' {
  interface Slots { 'task.badge': { taskId: string } }
}
const badges = definePlugin({ name: 'badges', setup(scope) {
  scope.contribute(slot('task.badge'), 'badge renderer')
} })
const kernel = createKernel()
kernel.load(badges)
console.log(kernel.list(slot('task.badge')).length)
```

--------------------------------

### Install and uninstall plugins from an event handler

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Loads a plugin asynchronously from a module map and unloads it. Unloading cascades to dependents and is a no-op if the plugin is not loaded. The plugin object is the identity; loading the same object twice throws.

```ts
// an install button
async function install(id: string) {
  const mod = await pluginModules[id]()
  kernel.load(mod.default)
}
function uninstall(plugin: AnyPlugin) {
  kernel.unload(plugin)   // dependents cascade; no-op if not loaded
}
```

--------------------------------

### Define a plugin that provides a service (TypeScript)

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Use this to create a plugin that provides a service. The setup function creates a store, subscribes to changes, and provides the service. The kernel enforces that provided tokens must be listed in 'provides', otherwise it throws. Deferred functions run on dispose in LIFO order.

```TypeScript
import { definePlugin } from '@yatoi/kernel'

export const todosPlugin = definePlugin({
  name: 'todos',
  provides: [Todos],
  setup(scope) {
    const store = createStore(loadFromLocalStorage())
    const stop = store.subscribe(() => saveToLocalStorage(store.getAll()))
    scope.defer(stop)                 // undone on dispose, LIFO
    scope.provide(Todos, store)       // must be listed in `provides`
  },
})
```

--------------------------------

### TypeScript example: create kernel, define plugin and service

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/packages/kernel/README.md

Import createKernel, definePlugin, defineService from '@yatoi/kernel'. Define a Clock service, a plugin providing the service and deferring a stop, a reader plugin injecting the Clock, and load both plugins.

```ts
import { createKernel, definePlugin, defineService } from '@yatoi/kernel'
const Clock = defineService<{ now(): number }>('clock')
const clock = definePlugin({ name: 'clock', provides: [Clock], setup(scope) {
  const timer = { stop() {} }
  scope.provide(Clock, { now: () => Date.now() })
  scope.defer(() => timer.stop())
} })
const reader = definePlugin({ name: 'reader', inject: [Clock], setup(scope) {
  console.log(scope.get(Clock).now())
} })
const kernel = createKernel()
kernel.load(clock, reader)

```

--------------------------------

### Define a plugin that depends on a service (TypeScript)

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Use this to create a plugin that depends on other services. The injected tokens are typed non-null and snapshotted at activation. The setup function gets the services and sets up a periodic task, deferring cleanup. If the underlying service changes, the scope is disposed and re-run.

```TypeScript
export const syncPlugin = definePlugin({
  name: 'sync',
  inject: [Todos, Clock],
  setup(scope) {
    const todos = scope.get(Todos)     // TodoStore, not TodoStore | undefined
    const clock = scope.get(Clock)
    const id = setInterval(() => push(todos.getAll(), clock.now()), 5000)
    scope.defer(() => clearInterval(id))
  },
})
```

--------------------------------

### Use KernelProvider, Requires, and Slot with @yatoi/react

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/packages/react/README.md

Shows how to create a kernel, define a service and plugin, load the plugin, and render a React component using KernelProvider, Requires, and Slot. The plugin provides a Clock service and defers a cleanup log. The kernel is created outside the component tree and React observes it without owning it.

```tsx
import { createKernel, definePlugin, defineService } from '@yatoi/kernel'
import { KernelProvider, Requires } from '@yatoi/react'
import { Slot } from '@yatoi/react/slots'
declare module '@yatoi/slots' { interface Slots { 'sidebar.item': Record<never, never> } }
const Clock = defineService<{ now(): number }>('clock')
const clock = definePlugin({ name: 'clock', provides: [Clock], setup(scope) {
  scope.provide(Clock, { now: () => Date.now() })
  scope.defer(() => console.log('clock stopped'))
} })
const kernel = createKernel()
kernel.load(clock)
export function App() { return <KernelProvider kernel={kernel}>
  <Requires of={[Clock]}>{(value) => <time>{value.now()}</time>}</Requires>
  <Slot name="sidebar.item" />
</KernelProvider> }
```

--------------------------------

### Distinguish absent from starting up with useServiceState

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Returns a discriminated union indicating whether the service is present, absent, or loading. Use this when you need to differentiate between a service that is not yet available and one that is starting up.

```tsx
const s = useServiceState(Clock)         // { status: 'present', value } | { status: 'absent' } | { status: 'loading' }
```

--------------------------------

### Closure over setup-time service for a slot renderer

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/pitfalls.md

A slot renderer's signature is fixed by the `Slots` contract, so it cannot accept a service parameter. Use a closure to capture the service obtained via `scope.get` during setup. The renderer is then contributed with `contribute(scope, 'todo.item.extra', ...)`.

```tsx
function makeDueDateField(todos: TodoStore) {
  return function DueDateField({ todo }: SlotRendererProps<'todo.item.extra'>) { … }
}
contribute(scope, 'todo.item.extra', makeDueDateField(scope.get(Todos)))
```

--------------------------------

### Kernel plugin setup with temporal and spatial scoping

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/README.md

Defines a Clock service and two plugins: clockPlugin uses scope.defer for temporal cleanup and scope.provide for a reversible value; syncPlugin injects Clock and subscribes spatially, activating only while Clock is present. Loading order doesn't matter; unloading disposes sync first, and reloading gives sync a fresh scope.

```ts
import { createKernel, defineService, definePlugin } from '@yatoi/kernel'

const Clock = defineService<{ now(): number }>('clock')   // a real symbol, not a string

const clockPlugin = definePlugin({
  name: 'clock',
  provides: [Clock],
  setup(scope) {
    const id = setInterval(tick, 1000)
    scope.defer(() => clearInterval(id))            // temporal: undone on unload
    scope.provide(Clock, { now: () => Date.now() }) // temporal: removed on unload
  },
})

const syncPlugin = definePlugin({
  name: 'sync',
  inject: [Clock],                                  // spatial: runs only while Clock is present
  setup(scope) { scope.defer(subscribe(scope.get(Clock))) },  // typed non-null
})

const kernel = createKernel()
kernel.load(syncPlugin, clockPlugin)   // order doesn't matter; sync activates when Clock appears
kernel.unload(clockPlugin)             // sync disposes first, cleanups in reverse
kernel.load(clockPlugin)               // both come back, sync with a fresh scope
```

--------------------------------

### Factory pattern for closing over services (makeCalendarView)

Source: https://github.com/yatoi-dev/yatoi-js/blob/main/docs/guide.md

Creates a renderer component that closes over a service obtained from setup. Inline arrow functions do this naturally; for larger components, a factory keeps things readable. This is the idiomatic way to hand a setup-time dependency to a component React will call later, after setup has returned.

```tsx
function makeCalendarView(todos: TodoStore) {
  return function CalendarView() {
    const list = useTodos(todos)
    …
  }
}
scope.contribute(Views, { id: 'calendar', label: 'Calendar', View: makeCalendarView(todos) })
```
Tokens:
Raw