polywise: Skill for OpenCode

MobX State Management Guide

This skill provides mandatory specifications for using MobX and tsyringe (for dependency injection DI) for state management in this project.

1. Architecture Overview

• MobX: Core state management library (using makeAutoObservable).
• tsyringe: Dependency injection container for models.
• Modular Models: State is split into specialized models (e.g., GlobalModel, Settings).
• Auto-binding: Actions are automatically bound to class instances.

2. Model Implementation Patterns

2.1 Basic Model Structure

import { makeAutoObservable } from 'mobx'
import { injectable } from 'tsyringe'

@injectable()
export default class FeatureModel {
	count = 0
	loading = false

	constructor() {
		// ✅ Use autoBind: true for convenient event handling
		makeAutoObservable(this, {}, { autoBind: true })
	}

	increment() {
		this.count++
	}

	async fetchData() {
		this.loading = true
		try {
			// API call logic
		} finally {
			this.loading = false
		}
	}
}

2.2 Singleton Model (Root Store)

import { singleton } from 'tsyringe'

import { Settings } from '@/models'

@singleton()
export default class GlobalModel {
	// ✅ Dependency injection via constructor
	constructor(public settings: Settings) {}

	init() {
		this.settings.init()
	}

	off() {
		this.settings.off()
	}
}

2.3 Handling Complex Models (DI Composition)

For complex state management (more than 20 reactive variables), models should be split into smaller, focused sub-models and composed using DI.

// ✅ Recommended: split complex models into multiple sub-models and inject
@injectable()
export default class ComplexFeatureModel {
	constructor(
		public data: DataSubModel,
		public ui: UISubModel,
		public sync: SyncSubModel,
		public util: Util
	) {
		// Note: exclude injected dependencies, don't make them observable
		makeAutoObservable(this, { data: false, ui: false, sync: false, util: false }, { autoBind: true })
	}
}