@mobx-query/core 0.2.0

package/src/libs/mobx-query/entity/Entity.ts

@@ -0,0 +1,232 @@
+import {
+  action,
+  type IObjectDidChange,
+  isObservableArray,
+  isObservableMap,
+  observable,
+  observe,
+  toJS,
+} from "mobx";
+import type { EntityData, EntityEvents, EntityId } from "./types";
+import { MQClientAccessor } from "../client";
+import { invalidateQueryByHash } from "../utils";
+import { EntityState } from "./constants";
+
+export type EntityConstructor<
+  TData = unknown,
+  TEntityId extends EntityId = string,
+  E extends Entity<TData, TEntityId> = Entity<TData, TEntityId>,
+> = new () => E;
+
+export type EntityConstructorAny = EntityConstructor<
+  EntityData,
+  any,
+  EntityAny
+>;
+
+export type EntityAny = Entity<any, any>;
+
+const IGNORE_FIELDS: PropertyKey[] = ["isDirty", "state"] as const;
+
+export type EntityValueKeys<T> = {
+  [K in keyof T]: T[K] extends Function
+    ? never
+    : K extends "isDirty" | "state" | "queryHashes"
+      ? never
+      : K;
+}[keyof T] &
+  string;
+
+export abstract class Entity<
+  TData = unknown,
+  TEntityId extends EntityId = string,
+> extends MQClientAccessor {
+  abstract id: TEntityId;
+
+  abstract hydrate(data: TData): void;
+
+  readonly queryHashes = new Set<string>();
+
+  private events!: EntityEvents<TEntityId>;
+
+  @observable accessor state: EntityState = EntityState.CONFIRMED;
+  @observable accessor isDirty = false;
+
+  private readonly initValuesSnapshot: Map<string | number | symbol, unknown> =
+    new Map();
+
+  private isHydrated = false;
+
+  _init(queryHashes: string[], events: EntityEvents<TEntityId>) {
+    this.events = events;
+
+    for (const hash of queryHashes) {
+      this.queryHashes.add(hash);
+    }
+
+    observe(this, (change) => this.onObservableChange(change));
+  }
+
+  // @computed get isDirty() {
+  //   return this._isDirty
+  // }
+
+  _removeQueryHashes(hashes: string[]) {
+    for (const hash of hashes) {
+      this.queryHashes.delete(hash);
+    }
+
+    if (this.queryHashes.size === 0) {
+      this.events.onAllQueryHashesRemoved(this.id);
+    }
+  }
+
+  _markAsHydrated() {
+    this.isHydrated = true;
+  }
+
+  @action private onObservableChange(change: IObjectDidChange) {
+    if (change.type !== "update") {
+      return;
+    }
+
+    if (!this.isHydrated) {
+      return;
+    }
+
+    if (IGNORE_FIELDS.includes(change.name as any)) {
+      return;
+    }
+
+    // Store the initial value (deep cloned for complex data structures)
+    if (!this.initValuesSnapshot.has(change.name)) {
+      // Deep clone complex data structures (objects, arrays, nested observables)
+      // toJS converts observables to plain JS, effectively creating a deep clone
+      this.initValuesSnapshot.set(
+        change.name,
+        this.deepCloneValue(change.oldValue),
+      );
+    }
+
+    if (this.isDirty === false) {
+      this.isDirty = true;
+    }
+  }
+
+  /**
+   * Deep clones a value to ensure we store a snapshot, not a reference.
+   * Handles primitives, objects, arrays, and MobX observables.
+   */
+  private deepCloneValue(value: unknown): unknown {
+    // Handle null and undefined
+    if (value === null || value === undefined) {
+      return value;
+    }
+
+    // Handle primitives (string, number, boolean, symbol, bigint)
+    const valueType = typeof value;
+    if (
+      valueType === "string" ||
+      valueType === "number" ||
+      valueType === "boolean" ||
+      valueType === "symbol" ||
+      valueType === "bigint"
+    ) {
+      return value;
+    }
+
+    // Handle functions - store as-is (though they shouldn't typically be observable)
+    if (valueType === "function") {
+      return value;
+    }
+
+    if (value instanceof Date) {
+      return new Date(value.getTime());
+    }
+
+    if (value instanceof RegExp) {
+      return new RegExp(value);
+    }
+
+    if (value instanceof Set) {
+      return new Set(
+        Array.from(value).map((item) => this.deepCloneValue(item)),
+      );
+    }
+
+    if (value instanceof Map) {
+      const clonedMap = new Map();
+      for (const [key, val] of value.entries()) {
+        clonedMap.set(this.deepCloneValue(key), this.deepCloneValue(val));
+      }
+      return clonedMap;
+    }
+
+    // For objects and arrays (including MobX observables), use toJS to convert
+    // observables to plain JS and create a deep clone
+    try {
+      return toJS(value);
+    } catch (error) {
+      // Fallback: if toJS fails (e.g., circular reference), return as-is
+      // This is a safety measure, though it may not fully solve the problem
+      console.warn(
+        `Failed to deep clone value for property, using reference:`,
+        error,
+      );
+      return value;
+    }
+  }
+
+  @action reset() {
+    for (const [key, value] of this.initValuesSnapshot.entries()) {
+      // Deep clone the stored value before restoring to ensure we're not
+      // assigning a reference that might have been mutated
+      const clonedValue = this.deepCloneValue(value);
+
+      // @ts-expect-error: unknown field
+      const currentValue = this[key];
+
+      // Handle observable arrays and maps specially, similar to createViewModel
+      // This ensures proper restoration of MobX observable collections
+      if (isObservableArray(currentValue)) {
+        // For observable arrays, use replace() to restore the original array
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        currentValue.replace(clonedValue as any);
+      } else if (isObservableMap(currentValue)) {
+        // For observable maps, clear and merge to restore the original map
+        currentValue.clear();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        currentValue.merge(clonedValue as any);
+      } else {
+        // For other types, assign directly
+        // @ts-expect-error: unknown field
+        this[key] = clonedValue;
+      }
+    }
+
+    this._clearDirty();
+  }
+
+  @action _clearDirty() {
+    this.isDirty = false;
+    this.initValuesSnapshot.clear();
+  }
+
+  // isDirtyField(field: EntityValueKeys<this>) {
+  //   return this.initValuesSnapshot.has(field)
+  // }
+
+  // getOriginalValue<K extends EntityValueKeys<this>>(
+  //   field: K,
+  // ): this[K] | undefined {
+  //   return this.initValuesSnapshot.get(field) as this[K] | undefined
+  // }
+
+  invalidateRelatedQueries() {
+    const cache = this.queryClient.getQueryCache();
+
+    for (const hash of this.queryHashes) {
+      invalidateQueryByHash(hash, cache, () => this._removeQueryHashes([hash]));
+    }
+  }
+}

package/src/libs/mobx-query/entity/EntityCollection.ts

@@ -0,0 +1,285 @@
+import { action, computed, observable } from "mobx";
+import type { EntityConstructor, EntityConstructorAny } from "./Entity";
+import { QueryClient } from "@tanstack/react-query";
+import type { EntityDataAny, EntityId } from "./types";
+
+export class EntityCollection<
+  TEntityConstructor extends EntityConstructorAny = EntityConstructorAny,
+> {
+  @observable accessor collection = new Map<
+    EntityId,
+    InstanceType<TEntityConstructor>
+  >();
+  @observable accessor deletedRecordIds = new Set<EntityId>();
+  @observable accessor clientOnlyEntityIds = new Set<EntityId>();
+
+  constructor(
+    private readonly entityConstructor: EntityConstructor<
+      any,
+      any,
+      InstanceType<TEntityConstructor>
+    >,
+    private readonly queryClient: QueryClient,
+  ) {
+    this.initQueryClientCacheListener();
+  }
+
+  @computed get size() {
+    return this.collection.size;
+  }
+
+  @computed get entities() {
+    const entities: InstanceType<TEntityConstructor>[] = [];
+
+    for (const entity of this.collection.values()) {
+      if (this.deletedRecordIds.has(entity.id)) continue;
+      entities.push(entity);
+    }
+
+    return entities;
+  }
+
+  @computed get clientOnlyEntitiesMap() {
+    const entities = new Map<EntityId, InstanceType<TEntityConstructor>>();
+
+    for (const entityId of this.clientOnlyEntityIds.values()) {
+      const entity = this.collection.get(entityId);
+
+      if (!entity) {
+        continue;
+      }
+
+      entities.set(entityId, entity);
+    }
+
+    return entities;
+  }
+
+  @computed get clientOnlyEntities() {
+    const entities: InstanceType<TEntityConstructor>[] = [];
+
+    for (const entityId of this.clientOnlyEntityIds.values()) {
+      const entity = this.collection.get(entityId);
+
+      if (!entity) {
+        continue;
+      }
+
+      entities.push(entity);
+    }
+
+    return entities;
+  }
+
+  @action setEntity(data: EntityDataAny, queryHashes?: string[]) {
+    // if (clearQueryHashes && queryHashes) {
+    //   console.log('clearQueryHashes', queryHashes)
+    //   this.removeQueryHashesFromAllEntities(queryHashes)
+    // }
+
+    const entity =
+      new this.entityConstructor() as InstanceType<TEntityConstructor>;
+    entity.hydrate(data);
+    entity._markAsHydrated();
+
+    const prevEntity = this.collection.get(entity.id) as
+      | InstanceType<TEntityConstructor>
+      | undefined;
+
+    const updatedQueryHashes = prevEntity
+      ? [...prevEntity.queryHashes, ...(queryHashes || [])]
+      : [...(queryHashes || [])];
+
+    if (prevEntity) {
+      if (queryHashes) {
+        for (const hash of queryHashes) {
+          prevEntity.queryHashes.add(hash);
+        }
+      }
+
+      prevEntity.hydrate(data);
+      prevEntity._clearDirty();
+
+      return prevEntity;
+    }
+
+    entity._init(updatedQueryHashes, {
+      onAllQueryHashesRemoved: (entityId: EntityId) =>
+        this.deleteEntity(entityId),
+    });
+
+    this.collection.set(entity.id, entity);
+    return entity;
+  }
+
+  @action setEntities(entityData: EntityDataAny[], queryHashes: string[]) {
+    const entities: InstanceType<TEntityConstructor>[] = [];
+    const ids: EntityId[] = [];
+
+    if (!Array.isArray(entityData)) {
+      throw new Error("setEntities: entityData must be an array");
+    }
+
+    if (queryHashes) {
+      this.removeQueryHashesFromAllEntities(queryHashes);
+    }
+
+    for (const record of entityData) {
+      const entity = this.setEntity(record, queryHashes);
+      entities.push(entity);
+      ids.push(entity.id);
+    }
+
+    return [entities, ids] as const;
+  }
+
+  @action deleteEntity(entityId: EntityId) {
+    this.collection.delete(entityId);
+    this.clientOnlyEntityIds.delete(entityId);
+    this.deletedRecordIds.delete(entityId);
+  }
+
+  getEntityById(entityId: EntityId) {
+    return this.collection.get(entityId);
+  }
+
+  filter(
+    predicate: (
+      value: InstanceType<TEntityConstructor>,
+      index: number,
+    ) => boolean,
+  ): InstanceType<TEntityConstructor>[] {
+    const result: InstanceType<TEntityConstructor>[] = [];
+    let i = 0;
+    for (const entity of this.collection.values()) {
+      if (this.deletedRecordIds.has(entity.id)) continue;
+      if (predicate(entity, i++)) {
+        result.push(entity);
+      }
+    }
+    return result;
+  }
+
+  find(
+    predicate: (
+      value: InstanceType<TEntityConstructor>,
+      index: number,
+    ) => boolean,
+  ): InstanceType<TEntityConstructor> | undefined {
+    let i = 0;
+    for (const entity of this.collection.values()) {
+      if (this.deletedRecordIds.has(entity.id)) continue;
+      if (predicate(entity, i++)) {
+        return entity;
+      }
+    }
+    return undefined;
+  }
+
+  findIndex(
+    predicate: (
+      value: InstanceType<TEntityConstructor>,
+      index: number,
+    ) => boolean,
+  ): number {
+    let i = 0;
+    for (const entity of this.collection.values()) {
+      if (this.deletedRecordIds.has(entity.id)) continue;
+      if (predicate(entity, i)) {
+        return i;
+      }
+      i++;
+    }
+    return -1;
+  }
+
+  findLast(
+    predicate: (
+      value: InstanceType<TEntityConstructor>,
+      index: number,
+    ) => boolean,
+  ): InstanceType<TEntityConstructor> | undefined {
+    const entities = this.entities;
+    for (let i = entities.length - 1; i >= 0; i--) {
+      const entity = entities[i];
+      if (predicate(entity, i)) {
+        return entity;
+      }
+    }
+    return undefined;
+  }
+
+  findLastIndex(
+    predicate: (
+      value: InstanceType<TEntityConstructor>,
+      index: number,
+    ) => boolean,
+  ): number {
+    const entities = this.entities;
+    for (let i = entities.length - 1; i >= 0; i--) {
+      const entity = entities[i];
+      if (predicate(entity, i)) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  some(
+    predicate: (
+      value: InstanceType<TEntityConstructor>,
+      index: number,
+    ) => boolean,
+  ): boolean {
+    let i = 0;
+    for (const entity of this.collection.values()) {
+      if (this.deletedRecordIds.has(entity.id)) continue;
+      if (predicate(entity, i++)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  every(
+    predicate: (
+      value: InstanceType<TEntityConstructor>,
+      index: number,
+    ) => boolean,
+  ): boolean {
+    let i = 0;
+    for (const entity of this.collection.values()) {
+      if (this.deletedRecordIds.has(entity.id)) continue;
+      if (!predicate(entity, i++)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  map<T>(
+    predicate: (value: InstanceType<TEntityConstructor>, index: number) => T,
+  ): T[] {
+    const result: T[] = [];
+    let i = 0;
+    for (const entity of this.collection.values()) {
+      if (this.deletedRecordIds.has(entity.id)) continue;
+      result.push(predicate(entity, i++));
+    }
+    return observable.array(result);
+  }
+
+  private initQueryClientCacheListener() {
+    this.queryClient.getQueryCache().subscribe((event) => {
+      if (event.type === "removed") {
+        this.removeQueryHashesFromAllEntities([event.query.queryHash]);
+      }
+    });
+  }
+
+  private removeQueryHashesFromAllEntities(hashes: string[]) {
+    for (const entity of this.collection.values()) {
+      entity._removeQueryHashes(hashes);
+    }
+  }
+}

package/src/libs/mobx-query/entity/constants.ts

@@ -0,0 +1,7 @@
+export const EntityState = {
+  PENDING: "pending",
+  CONFIRMED: "confirmed",
+  FAILED: "failed",
+} as const;
+
+export type EntityState = (typeof EntityState)[keyof typeof EntityState];

package/src/libs/mobx-query/entity/index.ts

@@ -0,0 +1,15 @@
+import { Entity, type EntityConstructorAny, type EntityAny } from "./Entity";
+import { EntityCollection } from "./EntityCollection";
+import { EntityState } from "./constants";
+
+import type { EntityId, EntityData, EntityDataAny } from "./types";
+
+export { Entity, EntityState, EntityCollection };
+
+export type {
+  EntityConstructorAny,
+  EntityAny,
+  EntityData,
+  EntityDataAny,
+  EntityId,
+};

package/src/libs/mobx-query/entity/types.ts

@@ -0,0 +1,11 @@
+export type EntityId = string | number;
+
+export interface EntityData<TEntityId extends EntityId = string> {
+  id: TEntityId;
+}
+
+export type EntityDataAny = EntityData<EntityId>;
+
+export interface EntityEvents<TEntityId extends EntityId = string> {
+  onAllQueryHashesRemoved: (entityId: TEntityId) => void;
+}

package/src/libs/mobx-query/mutations/BatchMutationBase.ts

@@ -0,0 +1,105 @@
+import type {
+  DefaultError,
+  MutationFunctionContext,
+} from "@tanstack/react-query";
+import type { EntityConstructorAny, EntityCollection } from "../entity";
+import type {
+  BatchMutationInputInternal,
+  UseBatchMutationHookOptions,
+} from "./types";
+import { MutationBase } from "./MutationBase";
+
+export class BatchMutationBase<
+  TEntityConstructor extends EntityConstructorAny,
+  TError = DefaultError,
+  TMutateResult = unknown,
+> extends MutationBase<TEntityConstructor> {
+  protected readonly collection: EntityCollection<TEntityConstructor>;
+
+  constructor(
+    mutationPrefix: string,
+    protected readonly options: UseBatchMutationHookOptions<
+      TEntityConstructor,
+      TError,
+      TMutateResult
+    >,
+  ) {
+    super(mutationPrefix, options.entity);
+
+    this.collection = this.getEntityCollection(options.entity);
+  }
+
+  protected async onMutateBase(
+    input: BatchMutationInputInternal<TEntityConstructor>,
+    context: MutationFunctionContext,
+  ): Promise<TMutateResult> {
+    input.strategy.onMutate();
+    const result = await this.options.onMutate?.(input.entities, context);
+    return result ?? ({} as TMutateResult);
+  }
+
+  protected async onSuccessBase(
+    input: BatchMutationInputInternal<TEntityConstructor>,
+    onMutateResult: TMutateResult | undefined,
+    context: MutationFunctionContext,
+  ): Promise<void> {
+    input.strategy.onSuccess();
+    await this.options.onSuccess?.(input.entities, context, onMutateResult);
+  }
+
+  protected async onErrorBase(
+    error: TError,
+    input: BatchMutationInputInternal<TEntityConstructor>,
+    onMutateResult: TMutateResult | undefined,
+    context: MutationFunctionContext,
+  ): Promise<void> {
+    input.strategy.onError();
+    await this.options.onError?.(
+      error,
+      input.entities,
+      context,
+      onMutateResult,
+    );
+  }
+
+  protected async onSettledBase(
+    error: TError | null,
+    input: BatchMutationInputInternal<TEntityConstructor>,
+    onMutateResult: TMutateResult | undefined,
+    context: MutationFunctionContext,
+  ): Promise<void> {
+    await this.options.onSettled?.(
+      input.entities,
+      context,
+      onMutateResult,
+      error,
+    );
+  }
+
+  protected createInternalInput(
+    entities: InstanceType<TEntityConstructor>[],
+  ): BatchMutationInputInternal<TEntityConstructor> {
+    const dirtyEntities: InstanceType<TEntityConstructor>[] = [];
+
+    for (const entity of entities) {
+      if (!entity.isDirty) {
+        console.warn(
+          "Entity values has not been changed, mutation is skipped.",
+        );
+
+        continue;
+      }
+
+      dirtyEntities.push(entity);
+    }
+
+    return {
+      entities: dirtyEntities,
+      strategy: this.createMutationStrategy(dirtyEntities, {
+        invalidationStrategy: this.options.invalidationStrategy,
+        errorStrategy: this.options.errorStrategy,
+        invalidateOnError: this.options.invalidateOnError,
+      }),
+    };
+  }
+}

package/src/libs/mobx-query/mutations/BatchUpdateMutation.ts

@@ -0,0 +1,48 @@
+import { type DefaultError, useMutation } from "@tanstack/react-query";
+import type { EntityConstructorAny } from "../entity";
+import { BatchMutationBase } from "./BatchMutationBase";
+import type {
+  BatchMutationInputInternal,
+  UseBatchMutationHookOptions,
+} from "./types";
+
+export class BatchUpdateMutation<
+  TEntityConstructor extends EntityConstructorAny,
+  TError = DefaultError,
+  TMutateResult = unknown,
+> extends BatchMutationBase<TEntityConstructor, TError, TMutateResult> {
+  static readonly mutationPrefix = "__mutation__batch__update__";
+
+  constructor(
+    options: UseBatchMutationHookOptions<
+      TEntityConstructor,
+      TError,
+      TMutateResult
+    >,
+  ) {
+    super(BatchUpdateMutation.mutationPrefix, options);
+  }
+
+  useMutation() {
+    const mutation = useMutation<
+      void,
+      TError,
+      BatchMutationInputInternal<TEntityConstructor>,
+      TMutateResult
+    >({
+      mutationFn: (input) =>
+        this.options.mutationFn(input.entities, this.context),
+      onMutate: (input, context) => this.onMutateBase(input, context),
+      onSuccess: (_, input, onMutateResult, context) =>
+        this.onSuccessBase(input, onMutateResult, context),
+      onError: (error, input, onMutateResult, context) =>
+        this.onErrorBase(error, input, onMutateResult, context),
+      onSettled: (_, error, input, onMutateResult, context) =>
+        this.onSettledBase(error, input, onMutateResult, context),
+    });
+
+    return (entities: InstanceType<TEntityConstructor>[]) => {
+      mutation.mutate(this.createInternalInput(entities));
+    };
+  }
+}