castle-web-sdk 0.4.5 → 0.4.6

package/src/storage.ts

@@ -1,427 +0,0 @@
-import {
-  type SharedScope,
-  type StorageBlob,
-  type StorageUpdate,
-} from "./commands";
-import { CastleError } from "./errors";
-import { hostRequest } from "./transport";
-import type { Json } from "./types";
-
-const FLUSH_INTERVAL_MS = 2000;
-
-type EncodedValue = string | null;
-
-interface PendingRead {
-  resolve: (value: Json | null) => void;
-  reject: (error: unknown) => void;
-}
-
-interface ReadBatch {
-  bucketKey: string;
-  scope: SharedScope;
-  userId?: string;
-  reads: Map<string, PendingRead[]>;
-  scheduled: boolean;
-}
-
-export interface StorageApi {
-  get<T extends Json = Json>(key: string): Promise<T | null>;
-  set(key: string, value: Json): void;
-  remove(key: string): void;
-}
-
-export interface SharedStorageApi {
-  get<T extends Json = Json>(scope: "deck", key: string): Promise<T | null>;
-  get<T extends Json = Json>(scope: "user", key: string): Promise<T | null>;
-  get<T extends Json = Json>(
-    scope: "user",
-    userId: string,
-    key: string,
-  ): Promise<T | null>;
-  set(scope: SharedScope, key: string, value: Json): void;
-  remove(scope: SharedScope, key: string): void;
-}
-
-// Per-player private storage. The host stamps deckId/sessionId, so one deck
-// session = one stable blob: load once, then serve reads from cache and batch
-// writes on a 2s flush. Dirty writes overlay the server blob so an in-flight
-// write isn't clobbered by the flush response.
-class PrivateStorageImpl implements StorageApi {
-  private cache = new Map<string, Json>();
-  private dirty = new Map<string, EncodedValue>();
-  private loadPromise: Promise<void> | null = null;
-  private flushTimer: ReturnType<typeof setTimeout> | null = null;
-
-  async get<T extends Json = Json>(key: string): Promise<T | null> {
-    await this.ensureLoaded();
-    return (this.cache.get(key) ?? null) as T | null;
-  }
-
-  set(key: string, value: Json): void {
-    this.cache.set(key, value);
-    this.dirty.set(key, encodeStorageValue(value, "Storage.set"));
-    this.scheduleFlush();
-  }
-
-  remove(key: string): void {
-    this.cache.delete(key);
-    this.dirty.set(key, null);
-    this.scheduleFlush();
-  }
-
-  private ensureLoaded(): Promise<void> {
-    if (!this.loadPromise) {
-      this.loadPromise = this.load().catch((error: unknown) => {
-        this.loadPromise = null;
-        throw error;
-      });
-    }
-    return this.loadPromise;
-  }
-
-  private async load(): Promise<void> {
-    const { blob } = await hostRequest("deckStorage.load", {});
-    this.cache = decodeStorageBlob(blob, "Storage.get");
-    this.overlayDirty();
-  }
-
-  private async flush(): Promise<void> {
-    if (this.dirty.size === 0) return;
-    const snapshot = new Map(this.dirty);
-    const { blob } = await hostRequest("deckStorage.update", {
-      updates: updatesFromDirty(snapshot),
-    });
-    this.cache = decodeStorageBlob(blob, "Storage.flush");
-    clearAcknowledgedDirty(this.dirty, snapshot);
-    this.overlayDirty();
-  }
-
-  private overlayDirty(): void {
-    for (const [key, encoded] of this.dirty) {
-      if (encoded === null) this.cache.delete(key);
-      else this.cache.set(key, decodeStorageValue(encoded, "Storage.dirty"));
-    }
-  }
-
-  private scheduleFlush(): void {
-    if (this.flushTimer) return;
-    this.flushTimer = setTimeout(() => {
-      this.flushTimer = null;
-      void this.flush();
-    }, FLUSH_INTERVAL_MS);
-  }
-}
-
-// Cross-player storage. Writes always target the current player (the host
-// forces 'user'-scope writes to whoever is signed in), so dirty writes bucket
-// under a fixed key; reads of another player's 'user' bucket take an explicit
-// userId and never have pending writes. Reads coalesce per microtask into one
-// command with a keys[] array.
-class SharedStorageImpl implements SharedStorageApi {
-  private dirtyBuckets = new Map<string, Map<string, EncodedValue>>();
-  private readBatches = new Map<string, ReadBatch>();
-  private flushTimer: ReturnType<typeof setTimeout> | null = null;
-
-  async get<T extends Json = Json>(
-    scope: SharedScope,
-    userOrKey: string,
-    maybeKey?: string,
-  ): Promise<T | null> {
-    assertScope(scope, "SharedStorage.get");
-    const userId = scope === "user" && maybeKey ? userOrKey : undefined;
-    const key = maybeKey ?? userOrKey;
-    const dirty = this.peekDirty(scope, userId, key);
-    if (dirty !== undefined) {
-      return (
-        dirty === null ? null : decodeStorageValue(dirty, "SharedStorage.get")
-      ) as T | null;
-    }
-    return this.queueRead<T>(scope, userId, key);
-  }
-
-  set(scope: SharedScope, key: string, value: Json): void {
-    assertScope(scope, "SharedStorage.set");
-    this.write(scope, key, encodeStorageValue(value, "SharedStorage.set"));
-  }
-
-  remove(scope: SharedScope, key: string): void {
-    assertScope(scope, "SharedStorage.remove");
-    this.write(scope, key, null);
-  }
-
-  private write(scope: SharedScope, key: string, encoded: EncodedValue): void {
-    const bucketKey = writeBucketKey(scope);
-    const dirty =
-      this.dirtyBuckets.get(bucketKey) ?? new Map<string, EncodedValue>();
-    dirty.set(key, encoded);
-    this.dirtyBuckets.set(bucketKey, dirty);
-    this.scheduleFlush();
-  }
-
-  private peekDirty(
-    scope: SharedScope,
-    userId: string | undefined,
-    key: string,
-  ): EncodedValue | undefined {
-    if (scope === "user" && userId) return undefined;
-    return this.dirtyBuckets.get(writeBucketKey(scope))?.get(key);
-  }
-
-  private queueRead<T extends Json>(
-    scope: SharedScope,
-    userId: string | undefined,
-    key: string,
-  ): Promise<T | null> {
-    const bucketKey = readBucketKey(scope, userId);
-    let batch = this.readBatches.get(bucketKey);
-    if (!batch) {
-      batch = { bucketKey, scope, userId, reads: new Map(), scheduled: false };
-      this.readBatches.set(bucketKey, batch);
-    }
-    const reads = batch.reads.get(key) ?? [];
-    batch.reads.set(key, reads);
-    const promise = new Promise<Json | null>((resolve, reject) => {
-      reads.push({ resolve, reject });
-    });
-    if (!batch.scheduled) {
-      batch.scheduled = true;
-      queueMicrotask(() => void this.flushReadBatch(bucketKey));
-    }
-    return promise as Promise<T | null>;
-  }
-
-  private async flushReadBatch(bucketKey: string): Promise<void> {
-    const batch = this.readBatches.get(bucketKey);
-    if (!batch) return;
-    this.readBatches.delete(bucketKey);
-    const keys = Array.from(batch.reads.keys());
-    try {
-      const { blob } = await hostRequest("sharedDeckStorage.load", {
-        scope: batch.scope,
-        userId: batch.userId ?? null,
-        keys,
-      });
-      this.resolveReadBatch(batch, blob);
-    } catch (error) {
-      rejectReadBatch(batch, error);
-    }
-  }
-
-  private resolveReadBatch(batch: ReadBatch, blob: StorageBlob): void {
-    for (const [key, reads] of batch.reads) {
-      const encoded =
-        this.peekDirty(batch.scope, batch.userId, key) ?? blob[key] ?? null;
-      const value =
-        encoded === null
-          ? null
-          : decodeStorageValue(encoded, "SharedStorage.get");
-      for (const read of reads) read.resolve(value);
-    }
-  }
-
-  private async flush(): Promise<void> {
-    if (this.dirtyBuckets.size === 0) return;
-    const tasks = Array.from(this.dirtyBuckets, ([bucketKey, dirty]) =>
-      this.flushBucket(bucketKey, new Map(dirty)),
-    );
-    await Promise.all(tasks);
-  }
-
-  private async flushBucket(
-    bucketKey: string,
-    snapshot: Map<string, EncodedValue>,
-  ): Promise<void> {
-    if (snapshot.size === 0) return;
-    await hostRequest("sharedDeckStorage.update", {
-      scope: scopeFromWriteKey(bucketKey),
-      updates: updatesFromDirty(snapshot),
-    });
-    const dirty = this.dirtyBuckets.get(bucketKey);
-    if (!dirty) return;
-    clearAcknowledgedDirty(dirty, snapshot);
-    if (dirty.size === 0) this.dirtyBuckets.delete(bucketKey);
-  }
-
-  private scheduleFlush(): void {
-    if (this.flushTimer) return;
-    this.flushTimer = setTimeout(() => {
-      this.flushTimer = null;
-      void this.flush().catch(reportSharedStorageError);
-    }, FLUSH_INTERVAL_MS);
-  }
-}
-
-export const Storage: StorageApi = new PrivateStorageImpl();
-export const SharedStorage: SharedStorageApi = new SharedStorageImpl();
-
-// 'user'-scope writes/self-reads share one bucket (the host resolves the
-// current player); a 'user' read of someone else keys by their id.
-function writeBucketKey(scope: SharedScope): string {
-  return scope === "deck" ? "deck" : "user:self";
-}
-
-function readBucketKey(scope: SharedScope, userId: string | undefined): string {
-  if (scope === "deck") return "deck";
-  return userId ? `user:other:${userId}` : "user:self";
-}
-
-function scopeFromWriteKey(bucketKey: string): SharedScope {
-  return bucketKey === "deck" ? "deck" : "user";
-}
-
-function updatesFromDirty(dirty: Map<string, EncodedValue>): StorageUpdate[] {
-  return Array.from(dirty, ([key, value]) => ({ key, value }));
-}
-
-function clearAcknowledgedDirty(
-  dirty: Map<string, EncodedValue>,
-  acknowledged: Map<string, EncodedValue>,
-): void {
-  for (const [key, value] of acknowledged) {
-    if (dirty.get(key) === value) dirty.delete(key);
-  }
-}
-
-function decodeStorageBlob(
-  blob: StorageBlob,
-  operation: string,
-): Map<string, Json> {
-  return new Map(
-    Object.entries(blob).map(([key, value]) => [
-      key,
-      decodeStorageValue(value, operation),
-    ]),
-  );
-}
-
-function decodeStorageValue(encoded: string, operation: string): Json {
-  try {
-    return JSON.parse(encoded) as Json;
-  } catch {
-    throw storageError(
-      "CASTLE_STORAGE_PARSE_FAILED",
-      "Stored Castle value is not valid JSON.",
-      operation,
-    );
-  }
-}
-
-function encodeStorageValue(value: Json, operation: string): string {
-  try {
-    assertJsonValue(value, new Set(), operation);
-    return JSON.stringify(value);
-  } catch (error) {
-    if (error instanceof CastleError) throw error;
-    throw storageError(
-      "CASTLE_STORAGE_SERIALIZE_FAILED",
-      "Castle storage values must be JSON.",
-      operation,
-    );
-  }
-}
-
-function assertJsonValue(
-  value: unknown,
-  seen: Set<object>,
-  operation: string,
-): void {
-  if (value === null || typeof value === "boolean" || typeof value === "string")
-    return;
-  if (typeof value === "number") {
-    if (Number.isFinite(value)) return;
-    throw storageError(
-      "CASTLE_STORAGE_SERIALIZE_FAILED",
-      "Castle storage numbers must be finite.",
-      operation,
-    );
-  }
-  if (Array.isArray(value)) {
-    assertJsonArray(value, seen, operation);
-    return;
-  }
-  if (typeof value === "object") {
-    assertJsonObject(value, seen, operation);
-    return;
-  }
-  throw storageError(
-    "CASTLE_STORAGE_SERIALIZE_FAILED",
-    "Castle storage values must be JSON.",
-    operation,
-  );
-}
-
-function assertJsonArray(
-  values: unknown[],
-  seen: Set<object>,
-  operation: string,
-): void {
-  assertNotCyclic(values, seen, operation);
-  seen.add(values);
-  for (const value of values) assertJsonValue(value, seen, operation);
-  seen.delete(values);
-}
-
-function assertJsonObject(
-  value: object,
-  seen: Set<object>,
-  operation: string,
-): void {
-  assertNotCyclic(value, seen, operation);
-  const prototype = Object.getPrototypeOf(value) as unknown;
-  if (prototype !== Object.prototype && prototype !== null) {
-    throw storageError(
-      "CASTLE_STORAGE_SERIALIZE_FAILED",
-      "Castle storage objects must be plain JSON.",
-      operation,
-    );
-  }
-  seen.add(value);
-  for (const child of Object.values(value))
-    assertJsonValue(child, seen, operation);
-  seen.delete(value);
-}
-
-function assertNotCyclic(
-  value: object,
-  seen: Set<object>,
-  operation: string,
-): void {
-  if (seen.has(value)) {
-    throw storageError(
-      "CASTLE_STORAGE_SERIALIZE_FAILED",
-      "Castle storage values cannot be cyclic.",
-      operation,
-    );
-  }
-}
-
-function assertScope(
-  scope: string,
-  operation: string,
-): asserts scope is SharedScope {
-  if (scope !== "deck" && scope !== "user") {
-    throw storageError(
-      "CASTLE_STORAGE_INVALID_SCOPE",
-      'SharedStorage scope must be "deck" or "user".',
-      operation,
-    );
-  }
-}
-
-function rejectReadBatch(batch: ReadBatch, error: unknown): void {
-  for (const reads of batch.reads.values()) {
-    for (const read of reads) read.reject(error);
-  }
-}
-
-function reportSharedStorageError(error: unknown): void {
-  console.warn("Castle shared storage write failed", error);
-}
-
-function storageError(
-  code: string,
-  message: string,
-  operation: string,
-): CastleError {
-  return new CastleError({ code, message, operation });
-}

package/src/time.ts

@@ -1,202 +0,0 @@
-import { CastleError } from "./errors";
-import { hostRequest } from "./transport";
-import type { Json } from "./types";
-
-export type CastleClockZone = "player" | "Castle";
-
-export interface CastleDateParts {
-  sec: number;
-  min: number;
-  hour: number;
-  day: number;
-  month: number;
-  year: number;
-  wday: number;
-  yday: number;
-  daysSinceCastleEpoch: number;
-}
-
-export interface CastleTimeApi {
-  getServerTime(): Promise<number>;
-  getServerDate(timezone?: CastleClockZone): Promise<CastleDateParts>;
-}
-
-interface ServerTimeSnapshot {
-  offsetSeconds: number;
-  castleTimezoneOffsetMinutes: number;
-  daysSinceCastleEpoch: Record<CastleClockZone, number>;
-}
-
-let serverTimeSnapshot: ServerTimeSnapshot | null = null;
-let serverTimePromise: Promise<ServerTimeSnapshot> | null = null;
-
-export const Time: CastleTimeApi = {
-  getServerTime,
-  getServerDate,
-};
-
-async function getServerTime(): Promise<number> {
-  const snapshot = await syncServerTime();
-  return clientUnixSeconds() + snapshot.offsetSeconds;
-}
-
-async function getServerDate(
-  timezone: string = "Castle",
-): Promise<CastleDateParts> {
-  const operation = "Time.getServerDate";
-  const zone = clockZone(timezone, operation);
-  const snapshot = await syncServerTime();
-  return dateParts(
-    clientUnixSeconds() + snapshot.offsetSeconds,
-    zone,
-    snapshot,
-  );
-}
-
-async function syncServerTime(): Promise<ServerTimeSnapshot> {
-  if (serverTimeSnapshot) return serverTimeSnapshot;
-  if (!serverTimePromise) {
-    serverTimePromise = fetchServerTime().then((snapshot) => {
-      serverTimeSnapshot = snapshot;
-      return snapshot;
-    });
-  }
-  return serverTimePromise;
-}
-
-async function fetchServerTime(): Promise<ServerTimeSnapshot> {
-  const operation = "Time.getServerTime";
-  const data = await hostRequest("time.getServerTime", {});
-  const timestamp = numberField(
-    data.timestamp,
-    "serverTime.timestamp",
-    operation,
-  );
-  const timezoneOffset = numberField(
-    data.timezoneOffset,
-    "serverTime.timezoneOffset",
-    operation,
-  );
-  const epochData = jsonObject(
-    data.castleEpochData,
-    "serverTime.castleEpochData",
-    operation,
-  );
-  return {
-    offsetSeconds: snappedOffset(timestamp - clientUnixSeconds()),
-    castleTimezoneOffsetMinutes: timezoneOffset,
-    daysSinceCastleEpoch: {
-      Castle: numberField(
-        epochData.daysSinceServerTz,
-        "castleEpochData.daysSinceServerTz",
-        operation,
-      ),
-      player: numberField(
-        epochData.daysSinceUserTz,
-        "castleEpochData.daysSinceUserTz",
-        operation,
-      ),
-    },
-  };
-}
-
-function dateParts(
-  unixSeconds: number,
-  timezone: CastleClockZone,
-  snapshot: ServerTimeSnapshot,
-): CastleDateParts {
-  const shiftedSeconds =
-    timezone === "Castle"
-      ? unixSeconds + snapshot.castleTimezoneOffsetMinutes * 60
-      : unixSeconds;
-  const date = new Date(shiftedSeconds * 1000);
-  return timezone === "Castle"
-    ? utcDateParts(date, snapshot.daysSinceCastleEpoch.Castle)
-    : localDateParts(date, snapshot.daysSinceCastleEpoch.player);
-}
-
-function utcDateParts(
-  date: Date,
-  daysSinceCastleEpoch: number,
-): CastleDateParts {
-  return {
-    sec: date.getUTCSeconds(),
-    min: date.getUTCMinutes(),
-    hour: date.getUTCHours(),
-    day: date.getUTCDate(),
-    month: date.getUTCMonth() + 1,
-    year: date.getUTCFullYear(),
-    wday: date.getUTCDay() + 1,
-    yday: dayOfYear(
-      date.getUTCFullYear(),
-      date.getUTCMonth(),
-      date.getUTCDate(),
-    ),
-    daysSinceCastleEpoch,
-  };
-}
-
-function localDateParts(
-  date: Date,
-  daysSinceCastleEpoch: number,
-): CastleDateParts {
-  return {
-    sec: date.getSeconds(),
-    min: date.getMinutes(),
-    hour: date.getHours(),
-    day: date.getDate(),
-    month: date.getMonth() + 1,
-    year: date.getFullYear(),
-    wday: date.getDay() + 1,
-    yday: dayOfYear(date.getFullYear(), date.getMonth(), date.getDate()),
-    daysSinceCastleEpoch,
-  };
-}
-
-function dayOfYear(year: number, monthIndex: number, day: number): number {
-  const start = Date.UTC(year, 0, 1);
-  const current = Date.UTC(year, monthIndex, day);
-  return Math.floor((current - start) / 86400000) + 1;
-}
-
-function clockZone(timezone: string, operation: string): CastleClockZone {
-  const normalized = timezone.trim().toLowerCase();
-  if (normalized === "castle") return "Castle";
-  if (normalized === "player") return "player";
-  throw new CastleError({
-    code: "UNSUPPORTED_TIMEZONE",
-    message: 'Time.getServerDate timezone must be "Castle" or "player".',
-    operation,
-  });
-}
-
-function clientUnixSeconds(): number {
-  return Math.floor(Date.now() / 1000);
-}
-
-function snappedOffset(offsetSeconds: number): number {
-  return Math.abs(offsetSeconds) < 10 ? 0 : offsetSeconds;
-}
-
-function jsonObject(
-  value: Json,
-  field: string,
-  operation: string,
-): Record<string, Json> {
-  if (value !== null && typeof value === "object" && !Array.isArray(value))
-    return value;
-  throw new CastleError({
-    code: "GRAPHQL_BAD_DATA",
-    message: `Castle GraphQL field ${field} was not an object.`,
-    operation,
-  });
-}
-
-function numberField(value: Json, field: string, operation: string): number {
-  if (typeof value === "number" && Number.isFinite(value)) return value;
-  throw new CastleError({
-    code: "GRAPHQL_BAD_DATA",
-    message: `Castle GraphQL field ${field} was not a number.`,
-    operation,
-  });
-}