@evolu/common 7.4.1 → 8.0.0-next.0

package/src/Resources.ts

@@ -1,367 +0,0 @@
-import { err, ok, Result } from "./Result.js";
-import { PositiveInt } from "./Type.js";
-
-/**
- * A generic resource manager that handles reference counting and delayed
- * disposal of shared resources. Useful for managing expensive resources like
- * WebSocket connections that need to be shared among multiple consumers.
- */
-export interface Resources<
-  TResource extends Disposable,
-  TResourceKey extends string,
-  TResourceConfig,
-  TConsumer,
-  TConsumerId extends string,
-> extends Disposable {
-  /**
-   * Adds a consumer to resources, creating them if necessary. Increments
-   * reference counts for existing consumer-resource pairs.
-   */
-  readonly addConsumer: (
-    consumer: TConsumer,
-    resourceConfigs: ReadonlyArray<TResourceConfig>,
-  ) => void;
-
-  /**
-   * Removes a consumer from resources. Decrements reference counts and
-   * schedules disposal when no consumers remain.
-   *
-   * Returns an error if the resource doesn't exist or if the consumer wasn't
-   * added to the resource.
-   */
-  readonly removeConsumer: (
-    consumer: TConsumer,
-    resourceConfigs: ReadonlyArray<TResourceConfig>,
-  ) => Result<
-    void,
-    | ResourceNotFoundError<TResourceKey>
-    | ConsumerNotFoundError<TConsumerId, TResourceKey>
-  >;
-
-  /** Gets the resource for the specified key, or null if it doesn't exist. */
-  readonly getResource: (key: TResourceKey) => TResource | null;
-
-  /** Gets all consumer IDs currently using the specified resource key. */
-  readonly getConsumersForResource: (
-    key: TResourceKey,
-  ) => ReadonlyArray<TConsumerId>;
-
-  /** Checks if a consumer is currently using any resources. */
-  readonly hasConsumerAnyResource: (consumer: TConsumer) => boolean;
-
-  /**
-   * Gets the consumer for the specified consumer ID, or null if not found or
-   * not using any resources.
-   */
-  readonly getConsumer: (consumerId: TConsumerId) => TConsumer | null;
-}
-
-/** Error when trying to remove a consumer from a resource that doesn't exist. */
-export interface ResourceNotFoundError<TResourceKey extends string = string> {
-  readonly type: "ResourceNotFoundError";
-  readonly resourceKey: TResourceKey;
-}
-
-/** Error when trying to remove a consumer that wasn't added to a resource. */
-export interface ConsumerNotFoundError<
-  TConsumerId extends string = string,
-  TResourceKey extends string = string,
-> {
-  readonly type: "ConsumerNotFoundError";
-  readonly consumerId: TConsumerId;
-  readonly resourceKey: TResourceKey;
-}
-
-export interface ResourcesConfig<
-  TResource extends Disposable,
-  TResourceKey extends string,
-  TResourceConfig,
-  TConsumer,
-  TConsumerId extends string,
-> {
-  /** Creates a new resource for the given config. */
-  readonly createResource: (config: TResourceConfig) => TResource;
-
-  /** Extracts a unique key from a resource config for deduplication. */
-  readonly getResourceKey: (config: TResourceConfig) => TResourceKey;
-
-  /** Extracts a unique identifier from a consumer for reference counting. */
-  readonly getConsumerId: (consumer: TConsumer) => TConsumerId;
-
-  /**
-   * Delay in milliseconds before disposing unused resources. Helps avoid
-   * resource churn during rapid add/remove cycles. Defaults to 100ms.
-   */
-  readonly disposalDelay?: number;
-
-  /**
-   * Called when a consumer is added to a resource for the first time. This
-   * happens when the consumer's reference count goes from 0 to 1 for this
-   * resource.
-   */
-  readonly onConsumerAdded?: (
-    consumer: TConsumer,
-    resource: TResource,
-    resourceKey: TResourceKey,
-  ) => void;
-
-  /**
-   * Called when a consumer is completely removed from a resource. This happens
-   * when the consumer's reference count goes from 1 to 0 for this resource.
-   */
-  readonly onConsumerRemoved?: (
-    consumer: TConsumer,
-    resource: TResource,
-    resourceKey: TResourceKey,
-  ) => void;
-}
-
-/**
- * Creates {@link Resources}.
- *
- * This tracks which consumers are using which resources and maintains reference
- * counts to know when it's safe to dispose resources. Resources are created
- * on-demand and disposed with a configurable delay to avoid churn.
- *
- * ### Example Usage
- *
- * ```ts
- * // WebSocket connections
- * interface WebSocketConfig {
- *   readonly url: WebSocketUrl;
- * }
- *
- * type WebSocketUrl = string & Brand<"WebSocketUrl">;
- * type UserId = string & Brand<"UserId">;
- *
- * const webSockets = createResources<
- *   WebSocket,
- *   WebSocketUrl,
- *   WebSocketConfig,
- *   User,
- *   UserId
- * >({
- *   createResource: (config) => new WebSocket(config.url),
- *   getResourceKey: (config) => config.url,
- *   getConsumerId: (user) => user.id,
- *   disposalDelay: 1000,
- * });
- *
- * // Add users to WebSocket connections
- * webSockets.addConsumer(user1, [
- *   { url: "ws://server1.com" as WebSocketUrl },
- *   { url: "ws://server2.com" as WebSocketUrl },
- * ]);
- * webSockets.addConsumer(user2, [
- *   { url: "ws://server1.com" as WebSocketUrl },
- * ]);
- *
- * // Remove users - server1 stays alive (user2 still using it)
- * webSockets.removeConsumer(user1, [
- *   { url: "ws://server1.com" as WebSocketUrl },
- *   { url: "ws://server2.com" as WebSocketUrl },
- * ]);
- *
- * // server2 gets disposed after delay, server1 stays alive
- * ```
- */
-export const createResources = <
-  TResource extends Disposable,
-  TResourceKey extends string,
-  TResourceConfig,
-  TConsumer,
-  TConsumerId extends string,
->(
-  config: ResourcesConfig<
-    TResource,
-    TResourceKey,
-    TResourceConfig,
-    TConsumer,
-    TConsumerId
-  >,
-): Resources<
-  TResource,
-  TResourceKey,
-  TResourceConfig,
-  TConsumer,
-  TConsumerId
-> => {
-  let isDisposed = false;
-
-  const resourcesMap = new Map<TResourceKey, TResource>();
-  const consumerCounts = new Map<TResourceKey, Map<TConsumerId, PositiveInt>>();
-  const consumers = new Map<TConsumerId, TConsumer>();
-  const disposalTimeouts = new Map<
-    TResourceKey,
-    ReturnType<typeof setTimeout>
-  >();
-
-  const disposalDelay = config.disposalDelay ?? 100;
-
-  const ensureResource = (resourceConfig: TResourceConfig) => {
-    const key = config.getResourceKey(resourceConfig);
-    const timeout = disposalTimeouts.get(key);
-    if (timeout) {
-      clearTimeout(timeout);
-      disposalTimeouts.delete(key);
-    }
-
-    if (!resourcesMap.has(key)) {
-      const resource = config.createResource(resourceConfig);
-      resourcesMap.set(key, resource);
-    }
-  };
-
-  const scheduleDisposal = (key: TResourceKey): void => {
-    const timeout = setTimeout(() => {
-      const resource = resourcesMap.get(key);
-      if (resource) {
-        resource[Symbol.dispose]();
-        resourcesMap.delete(key);
-      }
-      disposalTimeouts.delete(key);
-    }, disposalDelay);
-
-    disposalTimeouts.set(key, timeout);
-  };
-
-  const resources: Resources<
-    TResource,
-    TResourceKey,
-    TResourceConfig,
-    TConsumer,
-    TConsumerId
-  > = {
-    addConsumer: (consumer, resourceConfigs) => {
-      if (isDisposed) return;
-
-      const consumerId = config.getConsumerId(consumer);
-
-      // Store consumer (last added consumer for this ID)
-      consumers.set(consumerId, consumer);
-
-      for (const resourceConfig of resourceConfigs) {
-        ensureResource(resourceConfig);
-        const resourceKey = config.getResourceKey(resourceConfig);
-
-        let counts = consumerCounts.get(resourceKey);
-        if (!counts) {
-          counts = new Map<TConsumerId, PositiveInt>();
-          consumerCounts.set(resourceKey, counts);
-        }
-
-        const currentCount = counts.get(consumerId) ?? 0;
-        const newCount = currentCount + 1;
-        counts.set(consumerId, PositiveInt.orThrow(newCount));
-
-        // Call onConsumerAdded callback only when consumer is added for the first time (0 -> 1)
-        if (currentCount === 0 && config.onConsumerAdded) {
-          const resource = resourcesMap.get(resourceKey);
-          if (resource) {
-            config.onConsumerAdded(consumer, resource, resourceKey);
-          }
-        }
-      }
-    },
-
-    removeConsumer: (consumer, resourceConfigs) => {
-      if (isDisposed) return ok();
-
-      const consumerId = config.getConsumerId(consumer);
-
-      for (const resourceConfig of resourceConfigs) {
-        const key = config.getResourceKey(resourceConfig);
-        const counts = consumerCounts.get(key);
-        if (!counts) {
-          return err({ type: "ResourceNotFoundError", resourceKey: key });
-        }
-
-        const currentCount = counts.get(consumerId);
-        if (currentCount == null) {
-          return err({
-            type: "ConsumerNotFoundError",
-            consumerId: consumerId,
-            resourceKey: key,
-          });
-        }
-
-        if (currentCount === 1) {
-          counts.delete(consumerId);
-
-          // Call onConsumerRemoved callback only when consumer is completely removed (1 -> 0)
-          if (config.onConsumerRemoved) {
-            const resource = resourcesMap.get(key);
-            if (resource) {
-              config.onConsumerRemoved(consumer, resource, key);
-            }
-          }
-
-          if (counts.size === 0) {
-            consumerCounts.delete(key);
-            scheduleDisposal(key);
-          }
-        } else {
-          counts.set(consumerId, PositiveInt.orThrow(currentCount - 1));
-        }
-      }
-
-      if (!resources.hasConsumerAnyResource(consumer)) {
-        consumers.delete(consumerId);
-      }
-
-      return ok();
-    },
-
-    getResource: (key) => {
-      if (isDisposed) return null;
-      return resourcesMap.get(key) ?? null;
-    },
-
-    getConsumersForResource: (key) => {
-      if (isDisposed) return [];
-      const counts = consumerCounts.get(key);
-      return counts ? Array.from(counts.keys()) : [];
-    },
-
-    hasConsumerAnyResource: (consumer) => {
-      if (isDisposed) return false;
-      const consumerId = config.getConsumerId(consumer);
-      // If slow, can be optimized with reverse index
-      return Array.from(consumerCounts.values()).some((counts) =>
-        counts.has(consumerId),
-      );
-    },
-
-    getConsumer: (consumerId) => {
-      if (isDisposed) return null;
-      const consumer = consumers.get(consumerId);
-      if (!consumer) return null;
-
-      // Only return consumer if it's currently using any resources
-      if (!resources.hasConsumerAnyResource(consumer)) {
-        return null;
-      }
-
-      return consumer;
-    },
-
-    [Symbol.dispose]: () => {
-      if (isDisposed) return;
-      isDisposed = true;
-
-      for (const timeout of disposalTimeouts.values()) {
-        clearTimeout(timeout);
-      }
-      disposalTimeouts.clear();
-
-      for (const resource of resourcesMap.values()) {
-        resource[Symbol.dispose]();
-      }
-      resourcesMap.clear();
-      consumerCounts.clear();
-      consumers.clear();
-    },
-  };
-
-  return resources;
-};

package/src/local-first/Platform.ts

@@ -1,27 +0,0 @@
-/**
- * FlushSync is for libraries like React to flush updates synchronously inside
- * the provided callback to ensure the DOM is updated immediately.
- *
- * For example, with React, when we want to focus on an element rendered as a
- * result of a mutation, Evolu ensures all DOM changes are flushed synchronously
- * if an onComplete callback is used.
- *
- * https://react.dev/reference/react-dom/flushSync
- */
-export type FlushSync = (callback: () => void) => void;
-
-export interface FlushSyncDep {
-  readonly flushSync: FlushSync;
-}
-
-/**
- * Reload the app in a platform-specific way.
- *
- * - **Web**: Redirects to the specified URL
- * - **React Native**: Restarts the app (URL parameter ignored)
- */
-export type ReloadApp = (url: string) => void;
-
-export interface ReloadAppDep {
-  readonly reloadApp: ReloadApp;
-}

package/src/local-first/Public.ts

@@ -1,42 +0,0 @@
-/**
- * Public local-first API exported from "@evolu/common"
- *
- * This module provides the supported consumer-facing API for Evolu's
- * local-first system: prefer importing from `@evolu/common` (this module) when
- * using Evolu in applications. If you require access to lower level internals,
- * consider importing from `@evolu/common/local-first`.
- *
- * @module
- */
-
-export { createEvolu } from "./Evolu.js";
-export type { Evolu, EvoluConfig, EvoluDeps, EvoluError } from "./Evolu.js";
-export type { UnuseOwner } from "./Evolu.js";
-export * from "./LocalAuth.js";
-export * from "./Owner.js";
-export * as kysely from "./PublicKysely.js";
-export type { InferRow, Query, QueryRows, Row } from "./Query.js";
-export type { EvoluSchema } from "./Schema.js";
-export type {
-  NetworkError,
-  PaymentRequiredError,
-  ServerError,
-  SyncOwner,
-  SyncState,
-  SyncStateInitial,
-  SyncStateIsNotSynced,
-  SyncStateIsSynced,
-  SyncStateIsSyncing,
-} from "./Sync.js";
-export {
-  Timestamp,
-  timestampBytesToTimestamp,
-  timestampToTimestampBytes,
-} from "./Timestamp.js";
-export type {
-  TimestampBytes,
-  TimestampCounterOverflowError,
-  TimestampDriftError,
-  TimestampError,
-  TimestampTimeOutOfRangeError,
-} from "./Timestamp.js";

package/src/local-first/PublicKysely.ts

@@ -1,239 +0,0 @@
-import {
-  AliasableExpression,
-  AliasNode,
-  ColumnNode,
-  Expression,
-  ExpressionWrapper,
-  IdentifierNode,
-  RawBuilder,
-  ReferenceNode,
-  SelectQueryNode,
-  Simplify,
-  sql,
-  TableNode,
-  ValueNode,
-} from "kysely";
-import { kyselyJsonIdentifier } from "./Query.js";
-
-export { sql } from "kysely";
-export type { NotNull } from "kysely";
-
-/**
- * A SQLite helper for aggregating a subquery into a JSON array.
- *
- * ### Examples
- *
- * ```ts
- * import { kysely } from "@evolu/common";
- *
- * // TODO: Update for Evolu
- * const result = await db
- *   .selectFrom("person")
- *   .select((eb) => [
- *     "id",
- *     kysely
- *       .jsonArrayFrom(
- *         eb
- *           .selectFrom("pet")
- *           .select(["pet.id as pet_id", "pet.name"])
- *           .whereRef("pet.owner_id", "=", "person.id")
- *           .orderBy("pet.name"),
- *       )
- *       .as("pets"),
- *   ])
- *   .execute();
- *
- * result[0]?.id;
- * result[0]?.pets[0].pet_id;
- * result[0]?.pets[0].name;
- * ```
- *
- * The generated SQL (SQLite):
- *
- * ```sql
- * select "id", (
- *   select coalesce(json_group_array(json_object(
- *     'pet_id', "agg"."pet_id",
- *     'name', "agg"."name"
- *   )), '[]') from (
- *     select "pet"."id" as "pet_id", "pet"."name"
- *     from "pet"
- *     where "pet"."owner_id" = "person"."id"
- *     order by "pet"."name"
- *   ) as "agg"
- * ) as "pets"
- * from "person"
- * ```
- */
-// Kysely expects strict AST.
-// prettier-ignore
-export function jsonArrayFrom<O>(
-    expr: SelectQueryBuilderExpression<O>,
-  ): RawBuilder<Array<Simplify<O>>> {
-    return sql`(select ${sql.lit(kyselyJsonIdentifier)} || coalesce(json_group_array(json_object(${sql.join(
-      getSqliteJsonObjectArgs(expr.toOperationNode(), 'agg'),
-    )})), '[]') from ${expr} as agg)`
-  }
-
-/**
- * A SQLite helper for turning a subquery into a JSON object.
- *
- * The subquery must only return one row.
- *
- * ### Examples
- *
- * ```ts
- * import { kysely } from "@evolu/common";
- *
- * // TODO: Update for Evolu
- * const result = await db
- *   .selectFrom("person")
- *   .select((eb) => [
- *     "id",
- *     jsonObjectFrom(
- *       eb
- *         .selectFrom("pet")
- *         .select(["pet.id as pet_id", "pet.name"])
- *         .whereRef("pet.owner_id", "=", "person.id")
- *         .where("pet.is_favorite", "=", true),
- *     ).as("favorite_pet"),
- *   ])
- *   .execute();
- *
- * result[0]?.id;
- * result[0]?.favorite_pet?.pet_id;
- * result[0]?.favorite_pet?.name;
- * ```
- *
- * The generated SQL (SQLite):
- *
- * ```sql
- * select "id", (
- *   select json_object(
- *     'pet_id', "obj"."pet_id",
- *     'name', "obj"."name"
- *   ) from (
- *     select "pet"."id" as "pet_id", "pet"."name"
- *     from "pet"
- *     where "pet"."owner_id" = "person"."id"
- *     and "pet"."is_favorite" = ?
- *   ) as obj
- * ) as "favorite_pet"
- * from "person";
- * ```
- */
-// Kysely expects strict AST.
-// prettier-ignore
-export function jsonObjectFrom<O>(
-    expr: SelectQueryBuilderExpression<O>,
-  ): RawBuilder<Simplify<O> | null> {
-    return sql`(select ${sql.lit(kyselyJsonIdentifier)} || json_object(${sql.join(
-      getSqliteJsonObjectArgs(expr.toOperationNode(), 'obj'),
-    )}) from ${expr} as obj)`
-  }
-
-/**
- * The SQLite `json_object` function.
- *
- * ### Examples
- *
- * ```ts
- * import { kysely } from "@evolu/common";
- *
- * // TODO: Update for Evolu
- * const result = await db
- *   .selectFrom("person")
- *   .select((eb) => [
- *     "id",
- *     kysely
- *       .jsonBuildObject({
- *         first: eb.ref("first_name"),
- *         last: eb.ref("last_name"),
- *         full: kysely.sql<string>`first_name || ' ' || last_name`,
- *       })
- *       .as("name"),
- *   ])
- *   .execute();
- *
- * result[0]?.id;
- * result[0]?.name.first;
- * result[0]?.name.last;
- * result[0]?.name.full;
- * ```
- *
- * The generated SQL (SQLite):
- *
- * ```sql
- * select "id", json_object(
- *   'first', first_name,
- *   'last', last_name,
- *   'full', "first_name" || ' ' || "last_name"
- * ) as "name"
- * from "person"
- * ```
- */
-// Kysely expects strict AST.
-// prettier-ignore
-export function jsonBuildObject<O extends Record<string, Expression<unknown>>>(
-    obj: O,
-  ): RawBuilder<
-    Simplify<{
-      [K in keyof O]: O[K] extends Expression<infer V> ? V : never
-    }>
-  > {
-    return sql`${sql.lit(kyselyJsonIdentifier)} || json_object(${sql.join(
-      Object.keys(obj).flatMap((k) => [sql.lit(k), obj[k]]),
-    )})`
-  }
-
-interface SelectQueryBuilderExpression<O> extends AliasableExpression<O> {
-  get isSelectQueryBuilder(): true;
-  toOperationNode(): SelectQueryNode;
-}
-
-function getSqliteJsonObjectArgs(
-  node: SelectQueryNode,
-  table: string,
-): Array<Expression<unknown> | string> {
-  try {
-    return getJsonObjectArgs(node, table);
-  } catch {
-    throw new Error(
-      "SQLite jsonArrayFrom and jsonObjectFrom functions can only handle explicit selections due to limitations of the json_object function. selectAll() is not allowed in the subquery.",
-    );
-  }
-}
-
-export function getJsonObjectArgs(
-  node: SelectQueryNode,
-  table: string,
-): Array<Expression<unknown> | string> {
-  const args: Array<Expression<unknown> | string> = [];
-  
-  for (const { selection: s } of node.selections ?? []) {
-    if (ReferenceNode.is(s) && ColumnNode.is(s.column)) {
-      args.push(
-        colName(s.column.column.name),
-        colRef(table, s.column.column.name),
-      );
-    } else if (ColumnNode.is(s)) {
-      args.push(colName(s.column.name), colRef(table, s.column.name));
-    } else if (AliasNode.is(s) && IdentifierNode.is(s.alias)) {
-      args.push(colName(s.alias.name), colRef(table, s.alias.name));
-    } else {
-      throw new Error(`can't extract column names from the select query node`);
-    }
-  }
-
-  return args;
-}
-
-function colName(col: string): Expression<unknown> {
-  return new ExpressionWrapper(ValueNode.createImmediate(col));
-}
-
-function colRef(table: string, col: string): Expression<unknown> {
-  return new ExpressionWrapper(
-    ReferenceNode.create(ColumnNode.create(col), TableNode.create(table)),
-  );
-}