rn-gamekit 0.1.0 → 0.2.1

package/src/storage/schema.ts

@@ -0,0 +1,147 @@
+import { GameStorageError, storageError } from './errors';
+import type { GameSaveSchema } from './types';
+import { validateMigrations, validateSchemaId, validateVersion } from './validation';
+import { cloneAndValidatePlainData } from './serialization';
+
+/**
+ * Define a versioned game save schema.
+ *
+ * Id/version/migrations are validated immediately. `createDefault` and
+ * `validate` are stored as-is — they run later per load/save.
+ */
+export function defineGameSave<TData>(options: {
+  id: string;
+  version: number;
+  createDefault: () => TData;
+  validate: (value: unknown) => TData;
+  migrations?: Readonly<Record<number, (value: unknown) => unknown>>;
+}): GameSaveSchema<TData> {
+  validateSchemaId(options.id);
+  validateVersion(options.version);
+  if (typeof options.createDefault !== 'function') {
+    throw new GameStorageError('createDefault must be a function', { code: 'INVALID_SCHEMA_ID', schemaId: options.id });
+  }
+  if (typeof options.validate !== 'function') {
+    throw new GameStorageError('validate must be a function', { code: 'VALIDATION_FAILED', schemaId: options.id });
+  }
+  const migrations = options.migrations ?? {};
+  validateMigrations(migrations as Readonly<Record<number, (value: unknown) => unknown>>, options.version);
+
+  // Freeze migrations shallowly — migration functions themselves remain.
+  const frozenMigrations = Object.freeze({ ...migrations });
+
+  const schema: GameSaveSchema<TData> = {
+    id: options.id,
+    version: options.version,
+    createDefault: options.createDefault,
+    validate: options.validate,
+    migrations: frozenMigrations,
+  };
+  return Object.freeze(schema) as GameSaveSchema<TData>;
+}
+
+/** Clone/freeze via plain-data path for defaults that are plain; fallback to structured clone for custom validation. */
+function deepFreeze<T>(value: T): T {
+  if (value === null || typeof value !== 'object') return value;
+  // Use storage-style freeze: we already cloned, just deep freeze.
+  const seen = new WeakSet<object>();
+  const freeze = (node: unknown): void => {
+    if (node === null || typeof node !== 'object') return;
+    const o = node as object;
+    if (seen.has(o)) return;
+    seen.add(o);
+    if (Array.isArray(node)) {
+      for (const v of node as unknown[]) freeze(v);
+    } else {
+      for (const v of Object.values(node as Record<string, unknown>)) freeze(v);
+    }
+    Object.freeze(node);
+  };
+  freeze(value);
+  return value;
+}
+
+export function createDefaultData<TData>(schema: GameSaveSchema<TData>): TData {
+  const raw = schema.createDefault();
+  // Validate through schema.validate to enforce domain rules and to
+  // ensure we return a newly owned, validated value. If validate does not
+  // clone, we still protect via plain-data clone.
+  try {
+    const validated = schema.validate(raw);
+    // Ensure plain-data safe and frozen
+    const cloned = cloneAndValidatePlainData(validated, 'createDefault() result') as TData;
+    return deepFreeze(cloned);
+  } catch (cause) {
+    if (cause instanceof GameStorageError) throw cause;
+    throw storageError(`createDefault() validation failed`, 'VALIDATION_FAILED', {
+      schemaId: schema.id,
+      schemaVersion: schema.version,
+      cause,
+    });
+  }
+}
+
+export function validateCurrentData<TData>(schema: GameSaveSchema<TData>, value: unknown, path = 'data'): TData {
+  try {
+    const validated = schema.validate(value);
+    const cloned = cloneAndValidatePlainData(validated, path) as TData;
+    return deepFreeze(cloned);
+  } catch (cause) {
+    if (cause instanceof GameStorageError) throw cause;
+    // Preserve original validation error as cause; surface as VALIDATION_FAILED with path if available
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    throw storageError(msg, 'VALIDATION_FAILED', {
+      schemaId: schema.id,
+      schemaVersion: schema.version,
+      path,
+      cause,
+    });
+  }
+}
+
+export function migratePayload<TData>(
+  schema: GameSaveSchema<TData>,
+  storedVersion: number,
+  payload: unknown,
+): { data: unknown; fromVersion: number; toVersion: number } {
+  let current = payload;
+  let version = storedVersion;
+  const target = schema.version;
+  if (version > target) {
+    throw storageError(`stored version ${version} is newer than schema version ${target}`, 'FUTURE_VERSION', {
+      schemaId: schema.id,
+      schemaVersion: target,
+    });
+  }
+  if (version === target) return { data: current, fromVersion: version, toVersion: target };
+  // Sequential migrations version -> version+1
+  for (let v = version; v < target; v += 1) {
+    const fn = (schema.migrations as Record<number, (v: unknown) => unknown>)[v];
+    if (typeof fn !== 'function') {
+      throw storageError(`missing migration for version ${v} -> ${v + 1}`, 'MISSING_MIGRATION', {
+        schemaId: schema.id,
+        schemaVersion: target,
+        path: `migrations.${v}`,
+      });
+    }
+    try {
+      // Engine-owned deeply frozen input — migration must be pure and cannot mutate it.
+      const frozenInput = deepFreeze(cloneAndValidatePlainData(current, `migrations.${v} input`) as unknown);
+      const output = fn(frozenInput);
+      // Bounded-clone and freeze every migration output before the next step, so oversized/deep/unsupported intermediates are rejected at the step.
+      const clonedOutput = cloneAndValidatePlainData(output, `migrations.${v} output`);
+      deepFreeze(clonedOutput as unknown as object);
+      current = clonedOutput;
+      version = v + 1;
+    } catch (cause) {
+      if (cause instanceof GameStorageError) throw cause;
+      throw storageError(`migration ${v} -> ${v + 1} failed`, 'MIGRATION_FAILED', {
+        schemaId: schema.id,
+        schemaVersion: target,
+        path: `migrations.${v}`,
+        cause,
+      });
+    }
+  }
+  return { data: current, fromVersion: storedVersion, toVersion: target };
+}

package/src/storage/serialization.ts

@@ -0,0 +1,248 @@
+import type { GameStorageError } from './errors';
+import { storageError } from './errors';
+import { STORAGE_LIMITS, type StoredGameEnvelope } from './types';
+
+const ENVELOPE_FORMAT = 'rn-gamekit.save' as const;
+
+/**
+ * Bounded plain-data clone + validation for storage payloads.
+ *
+ * Mirrors the strictness of event payloads but with storage-sized limits.
+ * Rejects: functions, symbols, bigint, non-finite numbers, cycles,
+ * sparse holes, accessors, non-enumerable, unsafe prototype keys,
+ * array subclasses, class instances, React elements, thenables.
+ */
+export function cloneAndValidatePlainData(value: unknown, basePath = 'payload'): unknown {
+  let nodeCount = 0;
+  const ancestry = new WeakSet<object>();
+
+  const fail = (path: string, reason: string, code: GameStorageError['code'] = 'UNSUPPORTED_VALUE'): never => {
+    // Depth/size specific codes where useful
+    if (reason.includes('maximum depth')) {
+      throw storageError(`storage payload invalid at ${path}: ${reason}`, 'DEPTH_EXCEEDED', { path });
+    }
+    if (reason.includes('maximum payload size') || reason.includes('maximum serialized bytes') || reason.includes('exceeds maximum')) {
+      // Let caller turn size failures into SIZE_EXCEEDED where appropriate
+      if (reason.includes('nodes') || reason.includes('array') || reason.includes('object fields') || reason.includes('string')) {
+        throw storageError(`storage payload invalid at ${path}: ${reason}`, 'SIZE_EXCEEDED', { path });
+      }
+    }
+    throw storageError(`storage payload invalid at ${path}: ${reason}`, code, { path });
+  };
+
+  const isPlainRecord = (v: object): boolean => {
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+  };
+
+  const isReactElement = (v: object): boolean => {
+    const desc = Object.getOwnPropertyDescriptor(v as Record<string, unknown>, '$$typeof' as unknown as string);
+    if (desc !== undefined) return true;
+    return '$$typeof' in (v as Record<string, unknown>);
+  };
+
+  const clone = (val: unknown, path: string, depth: number): unknown => {
+    if (depth > STORAGE_LIMITS.MAX_DEPTH) {
+      fail(path, `exceeds maximum depth of ${STORAGE_LIMITS.MAX_DEPTH}`);
+    }
+    nodeCount += 1;
+    if (nodeCount > STORAGE_LIMITS.MAX_NODES) {
+      fail(path, `exceeds maximum payload size of ${STORAGE_LIMITS.MAX_NODES} nodes`);
+    }
+
+    if (val === null) return null;
+    const t = typeof val;
+    if (t === 'string') {
+      const s = val as string;
+      if (s.length > STORAGE_LIMITS.MAX_STRING_LENGTH) {
+        fail(path, `string exceeds maximum length of ${STORAGE_LIMITS.MAX_STRING_LENGTH}`);
+      }
+      return s;
+    }
+    if (t === 'boolean') return val;
+    if (t === 'number') {
+      const n = val as number;
+      if (!Number.isFinite(n)) fail(path, 'number must be finite');
+      return n;
+    }
+    if (t === 'bigint') fail(path, 'bigint is not a supported storage type');
+    if (t === 'symbol') fail(path, 'symbol is not a supported storage type');
+    if (t === 'function') fail(path, 'function is not a supported storage type');
+    if (t === 'undefined') fail(path, 'undefined is not a supported storage type (use null)');
+    if (t !== 'object') fail(path, `unsupported storage type "${t}"`);
+
+    const obj = val as object;
+    if (ancestry.has(obj)) fail(path, 'cycle detected in payload');
+    ancestry.add(obj);
+    try {
+      // GS-STORAGE-03 (coordinates GS-EVENT-03): thenables are rejected
+      // without invoking any user code. Only instanceof runs here; every
+      // other non-plain object fails at the array/record branches below.
+      // Own `then` functions are rejected later as function values.
+      if (obj instanceof Promise) {
+        fail(path, 'promise/thenable is not a supported storage type');
+      }
+      if (isReactElement(obj)) fail(path, 'React element is not a supported storage type');
+
+      if (Array.isArray(obj)) {
+        const arr = obj as unknown[];
+        if (Object.getPrototypeOf(arr) !== Array.prototype) fail(path, 'array subclass is not a supported storage type');
+        if (arr.length > STORAGE_LIMITS.MAX_ARRAY_LENGTH) fail(path, `array exceeds maximum length of ${STORAGE_LIMITS.MAX_ARRAY_LENGTH}`);
+        const descs = Object.getOwnPropertyDescriptors(arr);
+        for (let i = 0; i < arr.length; i += 1) {
+          const key = String(i);
+          if (!(key in descs)) fail(`${path}[${i}]`, 'sparse array holes are not supported');
+          const d = descs[key]!;
+          if (d.get !== undefined || d.set !== undefined) fail(`${path}[${i}]`, 'accessor property is not supported');
+          if (d.enumerable === false) fail(`${path}[${i}]`, 'non-enumerable property is not supported');
+        }
+        const cloned: unknown[] = new Array(arr.length);
+        for (let i = 0; i < arr.length; i += 1) {
+          const key = String(i);
+          const d = descs[key]!;
+          cloned[i] = clone(d.value, `${path}[${i}]`, depth + 1);
+        }
+        for (const key of Reflect.ownKeys(descs) as (string | symbol)[]) {
+          if (typeof key === 'symbol') fail(`${path}[Symbol(${String(key).slice(7, -1)})]`, 'symbol-keyed property is not supported');
+          const k = key as string;
+          if (k === 'length') continue;
+          if (/^(0|[1-9]\d*)$/.test(k)) {
+            const idx = Number(k);
+            if (idx < arr.length && String(idx) === k) continue;
+          }
+          if (k === '__proto__' || k === 'constructor' || k === 'prototype') fail(`${path}.${k}`, 'unsafe prototype key is not supported');
+          const d = descs[k]!;
+          if (d.get !== undefined || d.set !== undefined) fail(`${path}.${k}`, 'accessor property is not supported');
+          if (d.enumerable === false) fail(`${path}.${k}`, 'non-enumerable property is not supported');
+          fail(`${path}.${k}`, 'array extra property is not a supported storage member');
+        }
+        Object.freeze(cloned);
+        return cloned;
+      }
+
+      if (!isPlainRecord(obj)) fail(path, 'only plain records and arrays are supported (class instance, Map, Set, Date, etc. are rejected)');
+
+      const proto = Object.getPrototypeOf(obj);
+      const descs = Object.getOwnPropertyDescriptors(obj);
+      const keys = Object.keys(descs);
+      if (keys.length > STORAGE_LIMITS.MAX_OBJECT_FIELDS) {
+        fail(path, `object exceeds maximum field count of ${STORAGE_LIMITS.MAX_OBJECT_FIELDS}`);
+      }
+      for (const key of Reflect.ownKeys(descs) as (string | symbol)[]) {
+        if (typeof key === 'symbol') fail(`${path}[Symbol(${String(key).slice(7, -1)})]`, 'symbol-keyed property is not supported');
+        const k = key as string;
+        if (k === '__proto__' || k === 'constructor' || k === 'prototype') fail(`${path}.${k}`, 'unsafe prototype key is not supported');
+        const d = descs[k]!;
+        if (d.get !== undefined || d.set !== undefined) fail(`${path}.${k}`, 'accessor property is not supported');
+        if (d.enumerable === false) fail(`${path}.${k}`, 'non-enumerable property is not supported');
+      }
+      const cloned: Record<string, unknown> = proto === null ? Object.create(null) : {};
+      for (const key of keys) {
+        const d = descs[key]!;
+        cloned[key] = clone(d.value, `${path}.${key}`, depth + 1);
+      }
+      Object.freeze(cloned);
+      return cloned;
+    } finally {
+      ancestry.delete(obj);
+    }
+  };
+
+  const result = clone(value, basePath, 0);
+  return result;
+}
+
+/**
+ * Exact UTF-8 byte length (GS-STORAGE-03): the single routine for every
+ * storage size check. TextEncoder is exact everywhere it exists (Node,
+ * browsers, modern Hermes); the scalar fallback below is bit-exact too,
+ * including unpaired surrogates (which encode as U+FFFD, 3 bytes).
+ */
+export function utf8ByteLength(str: string): number {
+  if (typeof TextEncoder !== 'undefined') {
+    return new TextEncoder().encode(str).length;
+  }
+  return utf8ByteLengthScalar(str);
+}
+
+/** Bit-exact scalar UTF-8 length for runtimes without TextEncoder. */
+export function utf8ByteLengthScalar(str: string): number {
+  let bytes = 0;
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i);
+    if (code < 0x80) {
+      bytes += 1;
+    } else if (code < 0x800) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff && i + 1 < str.length) {
+      const next = str.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+
+function serializedByteLength(str: string): number {
+  return utf8ByteLength(str);
+}
+
+export function serializeEnvelope(envelope: StoredGameEnvelope): string {
+  // Validate payload plain-data first
+  cloneAndValidatePlainData(envelope.payload, 'payload');
+  // Envelope itself is plain, but we validate its shape before stringify
+  if (envelope.format !== ENVELOPE_FORMAT) {
+    throw storageError(`envelope format must be "${ENVELOPE_FORMAT}"`, 'CORRUPT_ENVELOPE', { path: 'format' });
+  }
+  const json = JSON.stringify(envelope);
+  const bytes = serializedByteLength(json);
+  if (bytes > STORAGE_LIMITS.MAX_SERIALIZED_BYTES) {
+    throw storageError(`serialized envelope exceeds ${STORAGE_LIMITS.MAX_SERIALIZED_BYTES} bytes (got ${bytes})`, 'SIZE_EXCEEDED', {
+      path: 'envelope',
+    });
+  }
+  return json;
+}
+
+export function parseEnvelope(raw: string): StoredGameEnvelope {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw storageError(`corrupt envelope: JSON parse failed`, 'CORRUPT_ENVELOPE', { cause });
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw storageError(`corrupt envelope: expected object`, 'CORRUPT_ENVELOPE');
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (obj.format !== ENVELOPE_FORMAT) {
+    throw storageError(`corrupt envelope: expected format "${ENVELOPE_FORMAT}"`, 'CORRUPT_ENVELOPE', {
+      path: 'format',
+    });
+  }
+  if (typeof obj.schemaId !== 'string') {
+    throw storageError(`corrupt envelope: schemaId must be string`, 'CORRUPT_ENVELOPE', { path: 'schemaId' });
+  }
+  if (!Number.isSafeInteger(obj.schemaVersion)) {
+    throw storageError(`corrupt envelope: schemaVersion must be integer`, 'CORRUPT_ENVELOPE', {
+      path: 'schemaVersion',
+    });
+  }
+  if (typeof obj.savedAtMs !== 'number' || !Number.isFinite(obj.savedAtMs)) {
+    throw storageError(`corrupt envelope: savedAtMs must be finite number`, 'CORRUPT_ENVELOPE', {
+      path: 'savedAtMs',
+    });
+  }
+  if (!('payload' in obj)) {
+    throw storageError(`corrupt envelope: missing payload`, 'CORRUPT_ENVELOPE', { path: 'payload' });
+  }
+  return obj as unknown as StoredGameEnvelope;
+}
+
+export const STORAGE_ENVELOPE_FORMAT = ENVELOPE_FORMAT;