@colyseus/schema 5.0.21 → 5.0.23

package/build/types/HelperTypes.d.ts

@@ -8,7 +8,7 @@ import type { SetSchema } from "./custom/SetSchema.js";
 import type { StreamSchema } from "./custom/StreamSchema.js";
 import type { FieldBuilder } from "./builder.js";
 export type Constructor<T = {}> = new (...args: any[]) => T;
-type PrimitiveStringToType<T> = T extends "string" ? string : T extends "number" | "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" | "float32" | "float64" ? number : T extends "boolean" ? boolean : T;
+type PrimitiveStringToType<T> = T extends "string" ? string : T extends "number" | "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" | "float32" | "float64" ? number : T extends "bigint64" | "biguint64" ? bigint : T extends "boolean" ? boolean : T;
 /**
  * What the decoder callbacks accept as "a collection": the public shape, which
  * a plain array satisfies too — `@type([X]) items: X[]` is a common way to
@@ -23,7 +23,7 @@ export interface Collection<K = any, V = any, IT = V> extends CollectionLike<K,
     /** See {@link $resyncPrune} — every collection kind must declare its resync-sweep semantics. */
     [$resyncPrune](visited: Set<number | string>, prune: (value: V, identity: number | string) => void, keep: (value: V) => void): void;
 }
-export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : T extends "string" ? string : T extends "number" ? number : T extends "int8" ? number : T extends "uint8" ? number : T extends "int16" ? number : T extends "uint16" ? number : T extends "int32" ? number : T extends "uint32" ? number : T extends "int64" ? number : T extends "uint64" ? number : T extends "float32" ? number : T extends "float64" ? number : T extends "boolean" ? boolean : T extends {
+export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : T extends "string" ? string : T extends "number" ? number : T extends "int8" ? number : T extends "uint8" ? number : T extends "int16" ? number : T extends "uint16" ? number : T extends "int32" ? number : T extends "uint32" ? number : T extends "int64" ? number : T extends "uint64" ? number : T extends "float32" ? number : T extends "float64" ? number : T extends "bigint64" ? bigint : T extends "biguint64" ? bigint : T extends "boolean" ? boolean : T extends {
     type: infer ChildType extends PrimitiveType;
 } ? InferValueType<ChildType> : T extends {
     type: infer ChildType extends Constructor;
@@ -76,6 +76,18 @@ export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : T extends
 } ? StreamSchema<InstanceType<ChildType>> : T extends {
     stream: infer ChildType;
 } ? StreamSchema<ChildType> : T extends Constructor ? InstanceType<T> : T extends Record<string | number, string | number> ? T[keyof T] : T extends PrimitiveType ? T : never;
+/**
+ * Codecs that can carry a `T` — {@link InferValueType} run backwards, derived
+ * from it so the two can't drift. Constrains the element refinement in
+ * `t.array<Mark>("uint8")`; `never` (an uncallable overload) when no codec
+ * decodes into `T`.
+ *
+ * `[T] extends [...]` is deliberate: a distributive check would let a mixed
+ * union like `string | number` match on either half.
+ */
+export type CodecFor<T> = {
+    [K in RawPrimitiveType]: [T] extends [InferValueType<K>] ? K : never;
+}[RawPrimitiveType];
 type IsOptionalBuilderKey<T, K extends keyof T> = T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean> ? O : false;
 type OptionalBuilderKeys<T> = {
     [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? K : never;

package/build/types/builder.d.ts

@@ -5,7 +5,7 @@ import type { CollectionSchema } from "./custom/CollectionSchema.js";
 import type { StreamSchema } from "./custom/StreamSchema.js";
 import type { Schema } from "../Schema.js";
 import type { DefinitionType, RawPrimitiveType } from "../annotations.js";
-import type { InferValueType, Constructor } from "./HelperTypes.js";
+import type { InferValueType, Constructor, CodecFor } from "./HelperTypes.js";
 import { $builder } from "./symbols.js";
 import { type QuantizeOptions } from "./quantize.js";
 /**
@@ -217,18 +217,22 @@ export type ChildType = RawPrimitiveType | Constructor<Schema>;
 interface ArrayFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<ArraySchema<T>, true, false>;
 }
 interface MapFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<MapSchema<T>, true, false>;
 }
 interface SetFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<SetSchema<T>, true, false>;
 }
 interface CollectionFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<CollectionSchema<T>, true, false>;
 }
 interface StreamFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<StreamSchema<InstanceType<C>>, true, false>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.21",
+  "version": "5.0.23",
   "description": "Automatic state replication for multiplayer games. Mutate plain objects, and every client gets a live, typed mirror through delta encoding.",
   "type": "module",
   "bin": {

package/src/codegen/api.ts

@@ -15,8 +15,9 @@ import * as lua from "./languages/lua.js";
 import * as c from "./languages/c.js";
 import * as gdscript from "./languages/gdscript.js";
 import * as dart from "./languages/dart.js";
+import * as swift from "./languages/swift.js";
 
-export const generators: Record<string, any> = { csharp, cpp, haxe, ts, js, java, lua, c, gdscript, dart, };
+export const generators: Record<string, any> = { csharp, cpp, haxe, ts, js, java, lua, c, gdscript, dart, swift, };
 
 export interface GenerateOptions {
     files: string[],

package/src/codegen/languages/swift.ts

@@ -0,0 +1,270 @@
+import {
+    Class,
+    Property,
+    File,
+    getCommentHeader,
+    Interface,
+    Enum,
+    Context,
+} from "../types.js";
+import { GenerateOptions } from "../api.js";
+
+export const name = "Swift";
+
+/**
+ * Swift types for interface (plain message) properties. Schema getters do not
+ * use this table: the `Colyseus` package reads every numeric field as `Double`
+ * through `SchemaView`, so all numeric schema types collapse there.
+ */
+const typeMaps: { [key: string]: string } = {
+    "string": "String",
+    "number": "Double",
+    "boolean": "Bool",
+    "int8": "Int",
+    "uint8": "Int",
+    "int16": "Int",
+    "uint16": "Int",
+    "int32": "Int",
+    "uint32": "Int",
+    "int64": "Int",
+    "uint64": "Int",
+    "float32": "Double",
+    "float64": "Double",
+}
+
+const enumNames = new Set<string>();
+
+const COMMON_IMPORTS = `import Colyseus`;
+
+const distinct = (value: string, index: number, self: string[]) =>
+    self.indexOf(value) === index;
+
+const isSchemaType = (childType: string) =>
+    childType !== undefined && /^[A-Z]/.test(childType) && !enumNames.has(childType);
+
+/**
+ * Swift Code Generator
+ *
+ * Emits typed façades over the `Colyseus` package's runtime: one `SchemaRef`
+ * subclass per schema, whose properties read through the shared handle on the
+ * instance the core decoded. Nothing is copied and nothing is stored, so a
+ * generated class stays correct as patches arrive.
+ *
+ * Collection properties return `MapSchema<T>` / `ArraySchema<T>`, which carry
+ * the field they came from — that is what `callbacks.onAdd(state.players, …)`
+ * registers against.
+ */
+
+/**
+ * Generate individual files for each class/interface/enum
+ */
+export function generate(context: Context, options: GenerateOptions): File[] {
+    context.enums.forEach((structure) => enumNames.add(structure.name));
+
+    return [
+        ...context.classes.map(klass => ({
+            name: `${klass.name}.swift`,
+            content: generateFile(generateClassBody(klass, context.classes, !!options.namespace), options)
+        })),
+        ...context.interfaces.map(structure => ({
+            name: `${structure.name}.swift`,
+            content: generateFile(generateInterfaceBody(structure), options),
+        })),
+        ...context.enums.filter(structure => structure.name !== 'OPERATION').map((structure) => ({
+            name: `${structure.name}.swift`,
+            content: generateFile(generateEnumBody(structure), options),
+        })),
+    ];
+}
+
+/**
+ * Generate a single bundled file containing all classes, interfaces, and enums
+ */
+export function renderBundle(context: Context, options: GenerateOptions): File {
+    const fileName = options.namespace ? `${options.namespace}.swift` : "Schema.swift";
+
+    context.enums.forEach((structure) => enumNames.add(structure.name));
+
+    const bodies = [
+        ...context.classes.map(klass => generateClassBody(klass, context.classes, !!options.namespace)),
+        ...context.interfaces.map(iface => generateInterfaceBody(iface)),
+        ...context.enums
+            .filter(structure => structure.name !== 'OPERATION')
+            .map(e => generateEnumBody(e)),
+    ].join("\n\n");
+
+    return { name: fileName, content: generateFile(bodies, options) };
+}
+
+/**
+ * Swift has no namespaces, so one stands in as a caseless enum. Declarations
+ * go inside it through an extension, which works the same whether they are
+ * bundled into one file or split across many.
+ */
+function generateFile(body: string, options: GenerateOptions): string {
+    const header = `${getCommentHeader()}
+
+${COMMON_IMPORTS}
+`;
+
+    if (!options.namespace) {
+        return `${header}
+${body}
+`;
+    }
+
+    return `${header}
+public enum ${options.namespace} {}
+
+extension ${options.namespace} {
+${indent(body)}
+}
+`;
+}
+
+function indent(text: string): string {
+    return text
+        .split("\n")
+        .map(line => (line.length > 0 ? `    ${line}` : line))
+        .join("\n");
+}
+
+function generateClassBody(klass: Class, allClasses: Class[], namespaced: boolean): string {
+    // A class nobody extends is final. One that is extended stays open so a
+    // consumer in another module can subclass it — except inside a namespace,
+    // where `open` conflicts with the extension's own access level and the
+    // subclass is generated alongside it anyway.
+    const isExtended = allClasses.some(other => other.extends === klass.name);
+    const modifier = isExtended ? (namespaced ? "public" : "open") : "public final";
+    const parent = (klass.extends === "Schema") ? "SchemaRef" : klass.extends;
+
+    const properties = klass.properties
+        .map(prop => generateProperty(prop))
+        .filter(Boolean)
+        .join("\n");
+
+    // Swift does not carry an `@unchecked Sendable` conformance across module
+    // boundaries, so every subclass has to restate it. What it asserts is the
+    // SDK's own contract: decoded state is read where it is pumped.
+    return `${modifier} class ${klass.name}: ${parent}, @unchecked Sendable {
+${properties}
+}`;
+}
+
+/**
+ * The Swift type a scalar schema field reads as, or undefined when the field
+ * can only be read dynamically (enum-typed and unknown types).
+ */
+function scalarSwiftType(type: string): string | undefined {
+    if (type === "string") { return "String"; }
+    if (type === "boolean") { return "Bool"; }
+    if (typeMaps[type] === "Double" || typeMaps[type] === "Int" || type === "quantized" || type === "number") {
+        return "Double";
+    }
+    return undefined;
+}
+
+function generateProperty(prop: Property): string {
+    const deprecation = (prop.deprecated)
+        ? `    @available(*, deprecated, message: "field '${prop.name}' is deprecated.")\n`
+        : '';
+
+    const escaped = escapeName(prop.name);
+    let body: string;
+
+    if (prop.childType && isSchemaType(prop.childType)) {
+        if (prop.type === "ref") {
+            body = `    public var ${escaped}: ${prop.childType}? { refOf("${prop.name}") }`;
+        } else if (prop.type === "map") {
+            body = `    public var ${escaped}: MapSchema<${prop.childType}> { mapOf("${prop.name}") }`;
+        } else {
+            body = `    public var ${escaped}: ArraySchema<${prop.childType}> { arrayOf("${prop.name}") }`;
+        }
+    } else if (prop.childType) {
+        // A collection of primitives. Everything numeric reads as Double, the
+        // same collapse the scalar getters make.
+        const child = typeMaps[prop.childType] === "String" ? "String" : "Double";
+        if (prop.type === "map") {
+            body = `    public var ${escaped}: MapSchema<${child}> { mapOf("${prop.name}") }`;
+        } else if (prop.type === "array") {
+            body = `    public var ${escaped}: ArraySchema<${child}> { arrayOf("${prop.name}") }`;
+        } else {
+            // A "ref" with a primitive child has no typed shape to offer.
+            body = `    public var ${escaped}: Double { view["${prop.name}"] }`;
+        }
+    } else {
+        const swiftType = scalarSwiftType(prop.type);
+        if (swiftType === "String") {
+            body = `    public var ${escaped}: String { view.string("${prop.name}") ?? "" }`;
+        } else if (swiftType === "Bool") {
+            body = `    public var ${escaped}: Bool { view.bool("${prop.name}") }`;
+        } else if (swiftType === "Double") {
+            body = `    public var ${escaped}: Double { view["${prop.name}"] }`;
+        } else {
+            // Enum-typed or unknown: read as the number the wire carries.
+            body = `    public var ${escaped}: Double { view["${prop.name}"] }`;
+        }
+    }
+
+    return deprecation + body;
+}
+
+/**
+ * Message payloads are plain structs rather than façades: they arrive as
+ * msgpack, not as decoded schema state.
+ */
+function generateInterfaceBody(struct: Interface): string {
+    const fields = struct.properties
+        .map(prop => `    public var ${escapeName(prop.name)}: ${getInterfaceType(prop)}?`)
+        .join("\n");
+
+    return `public struct ${struct.name}: Codable {
+${fields}
+
+    public init() {}
+}`;
+}
+
+function getInterfaceType(prop: Property): string {
+    if (prop.type === "array") {
+        return `[${typeMaps[prop.childType] ?? prop.childType ?? "Double"}]`;
+    }
+    return typeMaps[prop.type] ?? prop.type ?? "Double";
+}
+
+/**
+ * A namespace of constants rather than a Swift enum: Colyseus enums may carry
+ * string or floating-point values, and a Swift enum's raw type has to be one
+ * or the other.
+ */
+function generateEnumBody(_enum: Enum): string {
+    const members = _enum.properties
+        .map((prop, i) => {
+            let value: string;
+            if (prop.type) {
+                value = isNaN(Number(prop.type)) ? `"${prop.type}"` : `${Number(prop.type)}`;
+            } else {
+                value = `${i}`;
+            }
+            return `    public static let ${escapeName(prop.name)} = ${value}`;
+        })
+        .join("\n");
+
+    return `public enum ${_enum.name} {
+${members}
+}`;
+}
+
+/** Field names come from the server schema and may collide with a keyword. */
+const SWIFT_KEYWORDS = new Set([
+    "associatedtype", "class", "deinit", "enum", "extension", "fileprivate", "func", "import",
+    "init", "inout", "internal", "let", "open", "operator", "private", "precedencegroup",
+    "protocol", "public", "rethrows", "static", "struct", "subscript", "typealias", "var",
+    "break", "case", "catch", "continue", "default", "defer", "do", "else", "fallthrough",
+    "for", "guard", "if", "in", "repeat", "return", "throw", "switch", "where", "while",
+    "Any", "as", "await", "false", "is", "nil", "self", "Self", "super", "throws", "true", "try",
+]);
+
+function escapeName(name: string): string {
+    return SWIFT_KEYWORDS.has(name) ? `\`${name}\`` : name;
+}

package/src/types/HelperTypes.ts

@@ -14,6 +14,7 @@ export type Constructor<T = {}> = new (...args: any[]) => T;
 type PrimitiveStringToType<T> =
     T extends "string" ? string
     : T extends "number" | "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" | "float32" | "float64" ? number
+    : T extends "bigint64" | "biguint64" ? bigint
     : T extends "boolean" ? boolean
     : T;
 
@@ -53,6 +54,8 @@ export type InferValueType<T> =
     : T extends "uint64" ? number
     : T extends "float32" ? number
     : T extends "float64" ? number
+    : T extends "bigint64" ? bigint
+    : T extends "biguint64" ? bigint
     : T extends "boolean" ? boolean
 
     // Handle { type: ... } patterns
@@ -95,6 +98,19 @@ export type InferValueType<T> =
 
     : never;
 
+/**
+ * Codecs that can carry a `T` — {@link InferValueType} run backwards, derived
+ * from it so the two can't drift. Constrains the element refinement in
+ * `t.array<Mark>("uint8")`; `never` (an uncallable overload) when no codec
+ * decodes into `T`.
+ *
+ * `[T] extends [...]` is deliberate: a distributive check would let a mixed
+ * union like `string | number` match on either half.
+ */
+export type CodecFor<T> = {
+    [K in RawPrimitiveType]: [T] extends [InferValueType<K>] ? K : never
+}[RawPrimitiveType];
+
 // Keys whose builder carries the `.optional()` brand. Reads the brand rather
 // than `undefined extends V`: the latter is true for EVERY V when the consumer
 // compiles with `strictNullChecks: false`, flipping all fields optional.

package/src/types/builder.ts

@@ -5,7 +5,7 @@ import type { CollectionSchema } from "./custom/CollectionSchema.js";
 import type { StreamSchema } from "./custom/StreamSchema.js";
 import type { Schema } from "../Schema.js";
 import type { DefinitionType, RawPrimitiveType } from "../annotations.js";
-import type { InferValueType, Constructor } from "./HelperTypes.js";
+import type { InferValueType, Constructor, CodecFor } from "./HelperTypes.js";
 import { $builder } from "./symbols.js";
 import { ARRAY_STREAM_NOT_SUPPORTED } from "../encoder/streaming.js";
 import { resolveQuantize, type QuantizeOptions } from "./quantize.js";
@@ -337,21 +337,28 @@ function resolveChild(child: ChildType): DefinitionType {
 // overloads narrow the return type for Schema/primitive children.
 // All collection factories tag `HasDefault = true` because schema() auto-
 // instantiates an empty collection when no explicit default is given.
+//
+// The third overload refines the ELEMENT type (`t.map<V>` — the value, never
+// the key), with the same type-level-only caveat as `PrimitiveFactory` above.
 interface ArrayFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<ArraySchema<T>, true, false>;
 }
 interface MapFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<MapSchema<T>, true, false>;
 }
 interface SetFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<SetSchema<T>, true, false>;
 }
 interface CollectionFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<CollectionSchema<T>, true, false>;
 }
 // t.stream(Entity) — priority-batched collection of Schema instances.
 // Element type is restricted to Schema subclasses (no primitives) because