POC for discussion

package.json

@@ -8,13 +8,16 @@
     "test:types": "vitest typecheck"
   },
   "dependencies": {
+    "lodash.isequal": "^4.5.0",
     "vue": "^3.4.21"
   },
   "devDependencies": {
+    "@types/lodash.isequal": "^4.5.8",
     "@vitejs/plugin-vue": "^5.0.4",
     "typescript": "^5.2.2",
     "vite": "^5.2.0",
     "vite-plugin-dts": "^3.7.3",
+    "vitest": "^1.4.0",
     "vue-tsc": "^2.0.6"
   }
 }

src/createChannel.ts

@@ -0,0 +1,77 @@
+import { reactive, readonly, ref } from "vue";
+import { Query, QueryAction, QueryOptions } from "./types";
+import { sequence } from "./utils";
+
+export type Channel<TAction extends QueryAction = any> = {
+  subscriptions: Map<number, QueryOptions>,
+  subscribe: (options?: QueryOptions) => Query<TAction>,
+}
+
+export function createChannel<TAction extends QueryAction>(action: TAction, parameters: Parameters<TAction>): Channel<TAction> {
+  const response = ref<Query<TAction>['response']>()
+  const error = ref<Query<TAction>['error']>()
+  const errored = ref<Query<TAction>['errored']>(false)
+  const executing = ref<Query<TAction>['executing']>(false)
+  const executed = ref<Query<TAction>['executed']>(false)
+
+  const subscriptions = new Map<number, QueryOptions>()
+  const { next: nextId } = sequence()
+
+  function execute(): void {
+    executing.value = true
+
+    try {
+      response.value = action(parameters)
+    } catch(err) {
+      error.value = err
+      errored.value = true
+
+      return
+    } finally {
+      executed.value = true
+      executing.value = false
+    }
+
+    error.value = undefined
+    errored.value = false
+  }
+
+  function update(): void {
+    if(!executed.value) {
+      execute()
+    }
+  }
+
+  function addSubscription(options?: QueryOptions): () => void {
+    const id = nextId()
+
+    subscriptions.set(id, options ?? {})
+
+    update()
+
+    return () => {
+      subscriptions.delete(id)
+      update()
+    }
+  }
+
+  function subscribe(options?: QueryOptions): Query<TAction> {
+    const unsubscribe = addSubscription(options)
+
+    const query: Query<TAction> = readonly(reactive({
+      response,
+      error,
+      errored,
+      executing,
+      executed,
+      unsubscribe,
+    }))
+
+    return query
+  }
+
+  return {
+    subscriptions,
+    subscribe
+  }
+}

src/createManager.ts

@@ -0,0 +1,64 @@
+import { reactive, toRefs } from "vue";
+import { Channel, createChannel } from "./createChannel";
+import { CreateQueryOptions, Query, QueryAction, QueryOptions } from "./types";
+
+export function createManager(options?: CreateQueryOptions) {
+  // might want to flatten this to a single map for simpler lookups
+  const channels = new Map<QueryAction, Map<string, Channel>>()
+
+  // should this be more elegant?
+  // this would break if there are function args I believe
+  function getParametersSignature(args: any[]): string {
+    return JSON.stringify(args)
+  }
+
+  function getChannel<
+    TAction extends QueryAction
+  >(action: TAction, parameters: Parameters<TAction>): Channel<TAction> {
+    if(!channels.has(action)) {
+      channels.set(action, new Map())
+    }
+
+    const actionChannels = channels.get(action)!
+    const argsString = getParametersSignature(parameters)
+
+    if(!actionChannels.has(argsString)) {
+      actionChannels.set(argsString, createChannel(action, parameters))
+    }
+
+    const channel = actionChannels.get(argsString)!
+
+    return channel
+  }
+
+  function deleteChannel<
+    TAction extends QueryAction
+  >(action: TAction, parameters: Parameters<TAction>): void {
+    const argsString = getParametersSignature(parameters)
+
+    channels.get(action)?.delete(argsString)
+  }
+
+  function subscribe<
+    TAction extends QueryAction
+  >(action: TAction, parameters: Parameters<TAction>, options?: QueryOptions): Query<TAction> {
+    const channel = getChannel(action, parameters)
+
+    const query = channel.subscribe(options)
+
+    return reactive({
+      ...toRefs(query),
+      unsubscribe: () => {
+        query.unsubscribe()
+
+        if(channel.subscriptions.size === 0) {
+          deleteChannel(action, parameters)
+        }
+      }
+    })
+  }
+
+  return {
+    subscribe
+  }
+}

src/createQuery.spec.ts

@@ -0,0 +1,13 @@
+import { test, expect, vi } from 'vitest'
+import { createQuery } from './createQuery'
+
+test('works', () => {
+  const action = vi.fn()
+  const { query } = createQuery()
+
+  query(action, [])
+  query(action, [])
+  query(action, [])
+
+  expect(action).toHaveBeenCalledOnce()
+})

src/createQuery.ts

@@ -0,0 +1,69 @@
+import { computed, onScopeDispose, reactive, toRefs, toValue, watch } from "vue";
+import { createManager } from "./createManager";
+import { CreateQueryOptions, DisposableQuery, Query, QueryAction, QueryActionArgs, QueryOptions } from "./types";
+import isEqual from 'lodash.isequal'
+import { isDefined } from "./utilities";
+
+export type QueryFunction = <TAction extends QueryAction>(action: TAction, args: Parameters<TAction>, options?: QueryOptions) => DisposableQuery<TAction>
+export type QueryComposition = <TAction extends QueryAction>(action: TAction, args: QueryActionArgs<TAction>, options?: QueryOptions) => Query<TAction>
+
+export type CreateQuery = {
+  query: QueryFunction,
+  useQuery: QueryComposition
+}
+
+const noop = () => undefined
+
+export function createQuery(options?: CreateQueryOptions): CreateQuery {
+  const manager = createManager(options)
+
+  const query: QueryFunction = (action, args, options) => {
+    const query = manager.subscribe(action, args, options)
+
+    return Object.assign(query, {
+      [Symbol.dispose]: () => {
+        query.unsubscribe()
+      },
+    })
+  }
+
+  const useQuery: QueryComposition = (action, parameters, options) => {
+    const value = query(noop, [])
+
+    watch(() => toValue(parameters), (parameters, previousParameters) => {
+      if(isDefined(previousParameters) && isEqual(previousParameters, parameters)) {
+        return
+      }
+
+      value.unsubscribe()
+
+      if(parameters === null) {
+        Object.assign(value, query(noop, []))
+        return
+      }
+
+      const newValue = query(action, parameters, options)
+
+      Object.assign(value, reactive({
+        ...toRefs(newValue),
+        response: computed(() => {
+          if(newValue.executed) {
+            return newValue.response
+          }
+
+          return value.response
+        })
+      }))
+
+    }, { deep: true, immediate: true })
+
+    onScopeDispose(() => value.unsubscribe())
+
+    return value
+  }
+
+  return {
+    query,
+    useQuery,
+  }
+}

src/main.ts

@@ -0,0 +1,11 @@
+import { createQuery } from './createQuery'
+
+const { query, useQuery } = createQuery()
+
+export {
+  query,
+  useQuery,
+  createQuery,
+}
+
+export * from './types'

src/types.ts

@@ -0,0 +1,31 @@
+type MaybeGetter<T> = T | Getter<T>
+type Getter<T> = () => T
+type MaybePromise<T> = T | Promise<T>
+
+export type CreateQueryOptions = {
+  pauseActionsInBackground: boolean
+}
+
+export type QueryAction = (...args: any[]) => MaybePromise<any>
+
+export type QueryActionArgs<TAction extends QueryAction> = MaybeGetter<Parameters<TAction>> | Getter<null>
+
+export type QueryLifecycle = 'app' | 'route' | 'component'
+
+export type QueryOptions = {
+  maxAge?: number,
+  lifecycle?: QueryLifecycle
+}
+
+export type Query<TAction extends QueryAction> = {
+  response: ReturnType<TAction> | undefined,
+  error: unknown,
+  errored: boolean,
+  executed: boolean,
+  executing: boolean,
+  unsubscribe: () => void
+}
+
+export type DisposableQuery<TAction extends QueryAction> = Query<TAction> & {
+  [Symbol.dispose](): void;
+}

src/utilities.ts

@@ -0,0 +1,3 @@
+export function isDefined<T>(value: T | undefined): value is T {
+  return typeof value !== 'undefined'
+}

src/utils.ts

@@ -0,0 +1,7 @@
+export function sequence() {
+  let previous = 0
+
+  return {
+    next: () => previous += 1
+  }
+}

tsconfig.json

@@ -3,7 +3,7 @@
     "target": "ES2020",
     "useDefineForClassFields": true,
     "module": "ESNext",
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "lib": ["ES2020", "DOM", "DOM.Iterable", "esnext.disposable"],
     "skipLibCheck": true,
     "paths": { "@/*": ["./src/*"],},
 
@@ -20,6 +20,6 @@
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true
   },
-  "include": ["src/**/*.ts", "src/**/*.vue"],
+  "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }