@matheuspuel/state-machine 0.1.0

package/.eslintrc.js

@@ -0,0 +1,34 @@
+module.exports = {
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+    'plugin:@typescript-eslint/strict',
+  ],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['./tsconfig.json'],
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+  },
+  ignorePatterns: [
+    '/.vscode/*',
+    '/coverage/*',
+    '/dist/*',
+    '/experiments/*',
+    '/node_modules/*',
+    '.eslintrc.js',
+    '.eslintrc.production.js',
+  ],
+  rules: {
+    // already checked by typescript
+    '@typescript-eslint/no-redeclare': 'off',
+    // warn instead of error
+    '@typescript-eslint/no-unused-vars': 'warn',
+    // allow namespace declaration for types
+    '@typescript-eslint/no-namespace': ['error', { allowDeclarations: true }],
+    // warn instead of error to prevent covering more specific errors
+    '@typescript-eslint/no-unsafe-return': 'warn',
+    '@typescript-eslint/no-unsafe-call': 'warn',
+  },
+}

package/.eslintrc.production.js

@@ -0,0 +1,11 @@
+const base = require('./.eslintrc.js')
+
+module.exports = {
+  ...base,
+  extends: [...base.extends, 'prettier'],
+  plugins: [...(base.plugins ?? []), 'prettier'],
+  rules: {
+    ...base.rules,
+    'prettier/prettier': ['warn'],
+  },
+}

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": false,
+  "trailingComma": "all",
+  "arrowParens": "avoid",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "endOfLine": "lf"
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@matheuspuel/state-machine",
+  "version": "0.1.0",
+  "type": "module",
+  "module": "index.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./src/index.ts",
+    "./mahcines": "./src/machines/index.ts",
+    "./react": "./src/react/index.ts",
+    "./runtime": "./src/runtime/index.ts"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0 --config .eslintrc.production.js",
+    "lint:fix": "eslint . --fix --config .eslintrc.production.js",
+    "typecheck": "tsc",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@matheuspuel/optic": "^0.1.0",
+    "effect": "^3.18.1",
+    "react": "19.1.0",
+    "use-sync-external-store": "^1.5.0"
+  },
+  "devDependencies": {
+    "@effect/language-service": "^0.41.1",
+    "@effect/vitest": "^0.26.0",
+    "@types/react": "~19.1.17",
+    "@types/use-sync-external-store": "^1.5.0",
+    "@typescript-eslint/parser": "^8.29.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "cross-env": "^7.0.3",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-plugin-prettier": "^5.2.6",
+    "prettier": "^3.6.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vite": "^6.3.5",
+    "vitest": "^3.2.4"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - esbuild

package/src/index.ts

@@ -0,0 +1,54 @@
+import { Optic } from '@matheuspuel/optic'
+
+export type MachineStoreBase<State> = {
+  get: () => State
+  update: (stateUpdate: (_: State) => State) => void
+}
+
+export type MachineStore<State> = MachineStoreBase<State> & {
+  zoom: <A, Optional extends boolean>(
+    f: (optic: Optic<State, State>) => Optic<A, State, Optional>,
+  ) => MachineStoreBase<A>
+}
+
+export const makeMachineStore = <State>(
+  base: MachineStoreBase<State>,
+): MachineStore<State> => ({
+  ...base,
+  zoom: zoomF => ({
+    get: () => (zoomF(Optic.id<State>()) as any).get(base.get()),
+    getOption: () => zoomF(Optic.id<State>()).getOption(base.get()),
+    update: f => base.update(zoomF(Optic.id<State>()).update(f)),
+  }),
+})
+
+export type StateAction<A extends unknown[], B> = (...args: A) => B
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyStateAction = StateAction<any[], unknown>
+
+export type AnyStateActions = Record<string, AnyStateAction>
+
+export type StateMachine<State, Actions extends AnyStateActions> = {
+  initialState: State
+  actions: (machine: { Store: MachineStore<State> }) => Actions
+  start?: (machine: {
+    Store: MachineStore<State>
+  }) => undefined | Promise<unknown>
+  onUpdate?: (state: State) => void | Promise<void>
+}
+
+export const makeStateMachine =
+  <State>() =>
+  <Actions extends AnyStateActions>(args: StateMachine<State, Actions>) =>
+    args
+
+export type PreparedStateActions<Actions extends AnyStateActions> = Actions
+
+export const prepareStateMachineActions = <
+  State,
+  Actions extends AnyStateActions,
+>(
+  machine: StateMachine<State, Actions>,
+  store: MachineStore<State>,
+): PreparedStateActions<Actions> => machine.actions({ Store: store })

package/src/machines/index.ts

@@ -0,0 +1 @@
+export * from './simple'

package/src/machines/simple.ts

@@ -0,0 +1,7 @@
+import { makeStateMachine } from '..'
+
+export const simpleStateMachine = <A>(initialState: A) =>
+  makeStateMachine<A>()({
+    initialState,
+    actions: ({ Store }) => ({ set: (value: A) => Store.update(() => value) }),
+  })

package/src/react/context.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react'
+import { AnyStateActions, PreparedStateActions, StateMachine } from '..'
+import { useStateMachine } from './useStateMachine'
+
+export const makeStateMachineContext = <State, Actions extends AnyStateActions>(
+  machine: StateMachine<State, Actions>,
+) => {
+  const Context = React.createContext<{
+    state: State
+    actions: PreparedStateActions<Actions>
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
+  }>(undefined as any)
+  return {
+    Provider: (props: { children: React.ReactNode }) => {
+      const value = useStateMachine(machine)
+      return <Context.Provider value={value}>{props.children}</Context.Provider>
+    },
+    useActions: () => React.useContext(Context).actions,
+    useSelector: <A,>(fn: (state: State) => A) => {
+      const state = React.useContext(Context).state
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      return React.useMemo(() => fn(state), [state])
+    },
+  }
+}

package/src/react/index.ts

@@ -0,0 +1,3 @@
+export * from './context'
+export * from './useSelector'
+export * from './useStateMachine'

package/src/react/useSelector.ts

@@ -0,0 +1,25 @@
+import { Effect, Equal, Equivalence } from 'effect'
+import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/with-selector'
+import { AnyStateActions } from '../index.js'
+import { RunningStateMachine } from '../runtime'
+
+export const makeUseSelector =
+  <State, Actions extends AnyStateActions>(
+    stateMachine: RunningStateMachine<State, Actions>,
+  ) =>
+  <A>(
+    selector: (state: State) => A,
+    equivalence?: Equivalence.Equivalence<A>,
+  ): A =>
+    useSyncExternalStoreWithSelector<State, A>(
+      onChange => {
+        const subscription = stateMachine
+          .subscribe(() => Effect.sync(onChange))
+          .pipe(Effect.runSync)
+        return () => subscription.unsubscribe.pipe(Effect.runSync)
+      },
+      () => stateMachine.ref.get.pipe(Effect.runSync),
+      undefined,
+      selector,
+      equivalence ?? Equal.equivalence<A>(),
+    )

package/src/react/useStateMachine.ts

@@ -0,0 +1,42 @@
+import * as React from 'react'
+import {
+  AnyStateActions,
+  makeMachineStore,
+  prepareStateMachineActions,
+  StateMachine,
+} from '..'
+
+export const useStateMachine = <State, Actions extends AnyStateActions>(
+  stateMachine:
+    | StateMachine<State, Actions>
+    | (() => StateMachine<State, Actions>),
+) => {
+  const machine =
+    typeof stateMachine === 'function' ? stateMachine() : stateMachine
+  const [state, setState] = React.useState(() => machine.initialState)
+  const stateRef = React.useRef(machine.initialState)
+  const getState = React.useMemo(() => () => stateRef.current, [])
+  const store = React.useMemo(
+    () =>
+      makeMachineStore<State>({
+        get: getState,
+        update: fn => {
+          const previousState = getState()
+          const state = fn(previousState)
+          stateRef.current = state
+          void machine.onUpdate?.(state)
+          setState(() => state)
+        },
+      }),
+    [machine, getState],
+  )
+  const actions = React.useMemo(
+    () => prepareStateMachineActions(machine, store),
+    [machine, store],
+  )
+  React.useEffect(() => {
+    void machine.start?.({ Store: store })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+  return { state, actions }
+}

package/src/runtime/index.ts

@@ -0,0 +1,56 @@
+import { Array, Effect, Ref } from 'effect'
+import {
+  AnyStateActions,
+  makeMachineStore,
+  PreparedStateActions,
+  prepareStateMachineActions,
+  StateMachine,
+} from '..'
+
+type SubscriptionTask<State> = (state: State) => Effect.Effect<void>
+
+export type RunningStateMachine<State, Actions extends AnyStateActions> = {
+  ref: Ref.Ref<State>
+  actions: PreparedStateActions<Actions>
+  startPromise: Promise<unknown> | undefined
+  subscribe: (
+    task: SubscriptionTask<State>,
+  ) => Effect.Effect<
+    { unsubscribe: Effect.Effect<void, never, never> },
+    never,
+    never
+  >
+}
+
+export const runStateMachine = <State, Actions extends AnyStateActions>(
+  machine: StateMachine<State, Actions>,
+): RunningStateMachine<State, Actions> => {
+  const subscriptionsRef = Ref.unsafeMake<SubscriptionTask<State>[]>([])
+  const ref = Ref.unsafeMake(machine.initialState)
+  const store = makeMachineStore<State>({
+    get: () => ref.get.pipe(Effect.runSync),
+    update: fn =>
+      Effect.gen(function* () {
+        const previousState = yield* ref.get
+        const state = fn(previousState)
+        yield* Ref.set(ref, state)
+        yield* Effect.forEach(yield* subscriptionsRef.get, _ => _(state)).pipe(
+          Effect.exit,
+        )
+        void machine.onUpdate?.(state)
+      }).pipe(Effect.runSync),
+  })
+  const actions = prepareStateMachineActions(machine, store)
+  const subscribe = (task: SubscriptionTask<State>) =>
+    Effect.gen(function* () {
+      yield* Ref.update(subscriptionsRef, Array.append(task))
+      return {
+        unsubscribe: Ref.update(
+          subscriptionsRef,
+          Array.filter(_ => _ !== task),
+        ),
+      }
+    })
+  const startPromise = machine.start?.({ Store: store })
+  return { ref, actions, subscribe, startPromise }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "target": "ESNext",
+    "jsx": "preserve",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "plugins": [{ "name": "@effect/language-service" }]
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}

package/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {},
+})