@colyseus/schema 5.0.22 → 5.0.24

package/build/codegen/languages/swift.d.ts

@@ -0,0 +1,23 @@
+import { File, Context } from "../types.js";
+import { GenerateOptions } from "../api.js";
+export declare const name = "Swift";
+/**
+ * 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 declare function generate(context: Context, options: GenerateOptions): File[];
+/**
+ * Generate a single bundled file containing all classes, interfaces, and enums
+ */
+export declare function renderBundle(context: Context, options: GenerateOptions): File;

package/build/types/HelperTypes.d.ts

@@ -89,16 +89,10 @@ 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;
-}[keyof T];
-type RequiredBuilderKeys<T> = {
-    [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? never : K;
-}[keyof T];
 export type InferSchemaInstanceType<T> = {
-    [K in RequiredBuilderKeys<T>]: T[K] extends FieldBuilder<any> ? InferValueType<T[K]> : T[K] extends (...args: any[]) => any ? (T[K] extends new (...args: any[]) => any ? InferValueType<T[K]> : T[K]) : InferValueType<T[K]>;
+    -readonly [K in keyof T as IsOptionalBuilderKey<T, K> extends true ? never : K]-?: T[K] extends FieldBuilder<any> ? InferValueType<T[K]> : T[K] extends (...args: any[]) => any ? (T[K] extends new (...args: any[]) => any ? InferValueType<T[K]> : T[K]) : InferValueType<T[K]>;
 } & {
-    [K in OptionalBuilderKeys<T>]?: T[K] extends FieldBuilder<infer V> ? V : never;
+    -readonly [K in keyof T as IsOptionalBuilderKey<T, K> extends true ? K : never]?: T[K] extends FieldBuilder<infer V> ? V : never;
 } & Schema;
 type DataKey<T, K extends keyof T> = K extends keyof Schema ? never : T[K] extends Function ? never : K;
 export type NonFunctionPropNames<T> = {
@@ -110,16 +104,10 @@ export type NonFunctionNonPrimitivePropNames<T> = {
 type ToJSONValue<U> = U extends Schema ? ToJSON<U> : PrimitiveStringToType<U>;
 type ToJSONField<X> = X extends MapSchema<infer U> ? Record<string, ToJSONValue<U>> : X extends Map<string, infer U> ? Record<string, ToJSONValue<U>> : X extends ArraySchema<infer U> ? ToJSONValue<U>[] : X extends SetSchema<infer U> ? ToJSONValue<U>[] : X extends CollectionSchema<infer U> ? ToJSONValue<U>[] : X extends Schema ? ToJSON<X> : X;
 type IsOptionalKey<T, K extends keyof T> = undefined extends {} ? ({} extends Pick<T, K> ? true : false) : (undefined extends T[K] ? true : false);
-type ToJSONRequiredKeys<T> = {
-    [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? never : K;
-}[keyof T];
-type ToJSONOptionalKeys<T> = {
-    [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? K : never;
-}[keyof T];
 export type ToJSON<T> = {
-    [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]>;
+    -readonly [K in keyof T as IsOptionalKey<T, K> extends true ? never : DataKey<T, K>]-?: ToJSONField<T[K]>;
 } & {
-    [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>>;
+    -readonly [K in keyof T as IsOptionalKey<T, K> extends true ? DataKey<T, K> : never]?: ToJSONField<Exclude<T[K], undefined>>;
 };
 /**
  * The plain DATA shape of a Schema instance type `T`: its synchronized fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.22",
+  "version": "5.0.24",
   "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

@@ -117,19 +117,19 @@ export type CodecFor<T> = {
 type IsOptionalBuilderKey<T, K extends keyof T> =
     T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean> ? O : false;
 
-// Per key, like `DataKey` below — an `Exclude<keyof T, …>` split defers every
-// key once one field is typed by a bare type parameter.
-type OptionalBuilderKeys<T> = { [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? K : never }[keyof T];
-type RequiredBuilderKeys<T> = { [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? never : K }[keyof T];
-
+// Split in the `as` clause, never over a precomputed key union: only a
+// homomorphic mapping carries each key back to its declaration in the
+// `schema({ … })` literal, which is what go-to-definition and rename resolve
+// through. `-readonly`, and `-?` on the required half, drop the modifiers a
+// homomorphic mapping inherits from the fields map.
 export type InferSchemaInstanceType<T> = {
-    [K in RequiredBuilderKeys<T>]: T[K] extends FieldBuilder<any>
+    -readonly [K in keyof T as IsOptionalBuilderKey<T, K> extends true ? never : K]-?: T[K] extends FieldBuilder<any>
         ? InferValueType<T[K]>
         : T[K] extends (...args: any[]) => any
             ? (T[K] extends new (...args: any[]) => any ? InferValueType<T[K]> : T[K])
             : InferValueType<T[K]>
 } & {
-    [K in OptionalBuilderKeys<T>]?: T[K] extends FieldBuilder<infer V>
+    -readonly [K in keyof T as IsOptionalBuilderKey<T, K> extends true ? K : never]?: T[K] extends FieldBuilder<infer V>
         ? V
         : never
 } & Schema;
@@ -170,15 +170,15 @@ type IsOptionalKey<T, K extends keyof T> = undefined extends {}
     ? ({} extends Pick<T, K> ? true : false)
     : (undefined extends T[K] ? true : false);
 
-// `DataKey` first: machinery and method keys drop before the optionality probe.
-type ToJSONRequiredKeys<T> = { [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? never : K }[keyof T];
-type ToJSONOptionalKeys<T> = { [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? K : never }[keyof T];
-
-// Keys are filtered before mapping: `ToJSONField` over the `this`-typed methods
-// exceeds TypeScript 7's instantiation depth.
+// Both filters live in the `as` clause, for two independent reasons:
+// navigation, as above — and depth, because the clause runs before the value
+// type, so `ToJSONField` never reaches the machinery, where it would recurse
+// through `restore(json: ToJSON<this>)` past TypeScript 7's instantiation limit.
+// Probing `IsOptionalKey` first is deliberate: `DataKey` then runs in the taken
+// branch only, once per key rather than once per half.
 export type ToJSON<T> =
-    & { [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]> }
-    & { [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>> };
+    & { -readonly [K in keyof T as IsOptionalKey<T, K> extends true ? never : DataKey<T, K>]-?: ToJSONField<T[K]> }
+    & { -readonly [K in keyof T as IsOptionalKey<T, K> extends true ? DataKey<T, K> : never]?: ToJSONField<Exclude<T[K], undefined>> };
 
 /**
  * The plain DATA shape of a Schema instance type `T`: its synchronized fields