@colyseus/schema 5.0.14 → 5.0.20

package/src/codegen/parser.ts

@@ -2,6 +2,7 @@ import * as ts from "typescript";
 import * as path from "path";
 import { readFileSync } from "fs";
 import { IStructure, Class, Interface, Property, Context, Enum, QuantizedProperty } from "./types.js";
+import { ResolveOptions, isOwnPackageSource, resetResolver, resolveNonRelativeImport, resolveSourceFile, sourceFileCandidates } from "./resolve.js";
 
 let currentStructure: IStructure;
 let currentProperty: Property;
@@ -14,10 +15,12 @@ const BUILDER_COLLECTION_KINDS = new Set(["array", "map", "set", "collection"]);
 
 /**
  * For a t.*().chain().calls() expression, walk down to the base `t.X(...)`
- * call and return its method name and first argument. Returns null if the
+ * call and return its method name, first argument, and the names of the
+ * chained modifiers (`.view()`, `.deprecated()`, …). Returns null if the
  * node does not look like a builder chain.
  */
-function extractBuilderBase(node: ts.CallExpression): { methodName: string, firstArg?: ts.Expression } | null {
+function extractBuilderBase(node: ts.CallExpression): { methodName: string, firstArg?: ts.Expression, modifiers: Set<string> } | null {
+    const modifiers = new Set<string>();
     let current: ts.CallExpression = node;
     while (true) {
         const expr = current.expression;
@@ -25,13 +28,14 @@ function extractBuilderBase(node: ts.CallExpression): { methodName: string, firs
             return null;
         }
         if (ts.isCallExpression(expr.expression)) {
-            // Chained modifier, e.g. .default() / .view() — walk deeper.
+            modifiers.add(expr.name.text);
             current = expr.expression;
             continue;
         }
         return {
             methodName: expr.name.text,
             firstArg: current.arguments[0],
+            modifiers,
         };
     }
 }
@@ -126,10 +130,27 @@ function defineProperty(property: Property, initializer: any) {
     if (ts.isCallExpression(initializer)) {
         const base = extractBuilderBase(initializer);
         if (base) {
+            // same as `@deprecated()`: `.deprecated(false)` still marks the field
+            if (base.modifiers.has("deprecated")) {
+                property.deprecated = true;
+            }
             if (BUILDER_COLLECTION_KINDS.has(base.methodName)) {
                 property.type = base.methodName;
                 if (base.firstArg) {
-                    property.childType = (base.firstArg as any).text ?? base.firstArg.getText();
+                    // see through `(x)`, `x as any`, `x satisfies T`
+                    let childArg: ts.Expression = base.firstArg;
+                    while (ts.isParenthesizedExpression(childArg) || ts.isAsExpression(childArg) || ts.isSatisfiesExpression(childArg)) {
+                        childArg = childArg.expression;
+                    }
+                    if (ts.isCallExpression(childArg)) {
+                        // mirrors the runtime guard in builder.ts resolveChild()
+                        const inner = extractBuilderBase(childArg);
+                        const hint = (inner && !BUILDER_COLLECTION_KINDS.has(inner.methodName) && inner.methodName !== "ref" && inner.methodName !== "quantized")
+                            ? `use the type name instead: t.${base.methodName}("${inner.methodName}")`
+                            : `collections accept a Schema class or a primitive type name ("string", "number", …)`;
+                        throw new Error(`schema-codegen: field '${property.name}': a t.* builder is not a valid element type — ${hint}.`);
+                    }
+                    property.childType = (childArg as any).text ?? childArg.getText();
                 }
             } else if (base.methodName === "ref") {
                 property.type = "ref";
@@ -169,15 +190,36 @@ function defineProperty(property: Property, initializer: any) {
     }
 }
 
+function followModuleSpecifier(
+    specifier: ts.Expression | undefined,
+    currentFile: string,
+    decoratorName: string,
+) {
+    const moduleName: string | undefined = (specifier as ts.StringLiteral)?.text;
+    if (!moduleName) { return; } // `export { x }` — no module to follow
+
+    const resolved = (moduleName.startsWith("."))
+        ? resolveSourceFile(path.resolve(path.dirname(currentFile), moduleName))
+        // may be a tsconfig `paths`/`baseUrl` alias onto first-party source;
+        // npm packages are filtered out by the resolver
+        : resolveNonRelativeImport(moduleName, currentFile);
+
+    if (resolved && !isOwnPackageSource(resolved)) {
+        parseFiles([resolved], decoratorName, globalContext);
+    }
+}
+
 function inspectNode(node: ts.Node, context: Context, decoratorName: string) {
     switch (node.kind) {
-        case ts.SyntaxKind.ImportClause:
-            const specifier = (node.parent as any).moduleSpecifier;
-            if (specifier && (specifier.text as string).startsWith('.')) {
-                const currentDir = path.dirname(node.getSourceFile().fileName);
-                const pathToImport = path.resolve(currentDir, specifier.text);
-                parseFiles([pathToImport], decoratorName, globalContext);
-            }
+        case ts.SyntaxKind.ImportDeclaration:
+        case ts.SyntaxKind.ExportDeclaration:
+            // ExportDeclaration too: path aliases usually point at a barrel
+            // (`@schemas` -> `schemas/index.ts` -> `export * from "./Player"`).
+            followModuleSpecifier(
+                (node as ts.ImportDeclaration | ts.ExportDeclaration).moduleSpecifier,
+                node.getSourceFile().fileName,
+                decoratorName,
+            );
             break;
 
         case ts.SyntaxKind.ClassDeclaration:
@@ -478,7 +520,10 @@ function inspectNode(node: ts.Node, context: Context, decoratorName: string) {
                     if (prop.kind === ts.SyntaxKind.MethodDeclaration) continue;
                     if (!prop.initializer) continue;
 
-                    const property = currentProperty || new Property();
+                    // never inherit `currentProperty`: it's the decorator path's
+                    // carry-over from a visited `deprecated` identifier, and a
+                    // trailing `.deprecated()` chain can leave it set
+                    const property = new Property();
                     property.name = prop.name.escapedText;
 
                     currentStructure.addProperty(property);
@@ -508,10 +553,15 @@ function inspectNode(node: ts.Node, context: Context, decoratorName: string) {
 
 let parsedFiles: { [filename: string]: boolean };
 
+/**
+ * `options` is only honored for a top-level call (one passing a fresh
+ * `Context`) — the recursive import walk reuses the run's resolver state.
+ */
 export function parseFiles(
     fileNames: string[],
     decoratorName: string = "type",
-    context: Context = new Context()
+    context: Context = new Context(),
+    options?: ResolveOptions,
 ) {
     if (typeof ts.createSourceFile !== "function") {
         // typescript@7+ (native) no longer ships the JS compiler API
@@ -527,30 +577,18 @@ export function parseFiles(
     if (globalContext !== context) {
         parsedFiles = {};
         globalContext = context;
+        // a structure left over from a previous run would make the
+        // `currentStructure?.name !== className` guard skip re-registering it
+        currentStructure = undefined;
+        currentProperty = undefined;
+        resetResolver(options);
     }
 
     fileNames.forEach((fileName) => {
         let sourceFile: ts.Node;
         let sourceFileName: string;
 
-        const fileNameAlternatives = [];
-
-        if (
-            !fileName.endsWith(".ts") &&
-            !fileName.endsWith(".js") &&
-            !fileName.endsWith(".mjs")
-        ) {
-            fileNameAlternatives.push(`${fileName}.ts`);
-            fileNameAlternatives.push(`${fileName}/index.ts`);
-
-        } else if (fileName.endsWith(".js")) {
-            // Handle .js extensions by also trying .ts (ESM imports often use .js extension)
-            fileNameAlternatives.push(fileName);
-            fileNameAlternatives.push(fileName.replace(/\.js$/, ".ts"));
-
-        } else {
-            fileNameAlternatives.push(fileName);
-        }
+        const fileNameAlternatives = sourceFileCandidates(fileName);
 
         for (let i = 0; i < fileNameAlternatives.length; i++) {
             try {

package/src/codegen/resolve.ts

@@ -0,0 +1,322 @@
+import * as ts from "typescript";
+import * as fs from "fs";
+import * as path from "path";
+
+import { PACKAGE_ROOT } from "./types.js";
+
+export interface ResolveOptions {
+    /** Explicit `--tsconfig`. When set, nearest-config discovery is skipped. */
+    tsconfig?: string;
+}
+
+interface ResolvedConfig {
+    configFilePath: string;
+    options: ts.CompilerOptions;
+    cache?: ts.ModuleResolutionCache;
+}
+
+interface MatchedPattern {
+    substitutions: string[];
+    /** What `*` captured, so substitutions can splice it back in. */
+    matchedStar: string;
+}
+
+const CONFIG_NAMES = ["tsconfig.json", "jsconfig.json"];
+
+/** `No inputs were found in config file` — expected, since readDirectory is stubbed. */
+const NO_INPUTS_FOUND = 18003;
+
+let configByDir: Map<string, ResolvedConfig | null>;
+let override: ResolvedConfig | null | undefined;
+let resolveOptions: ResolveOptions;
+let warned: Set<string>;
+
+reset();
+
+function reset() {
+    configByDir = new Map();
+    override = undefined;
+    resolveOptions = {};
+    warned = new Set();
+}
+
+/**
+ * Drop every cached tsconfig lookup. Called once per top-level `parseFiles()`
+ * run so a long-lived process can generate for two different projects.
+ */
+export function resetResolver(options: ResolveOptions = {}) {
+    reset();
+    resolveOptions = options;
+
+    if (options.tsconfig && !fs.existsSync(options.tsconfig)) {
+        throw new Error(`--tsconfig: file not found: ${options.tsconfig}`);
+    }
+}
+
+function warnOnce(key: string, message: string) {
+    if (warned.has(key)) { return; }
+    warned.add(key);
+    console.warn(message);
+}
+
+/**
+ * `readDirectory` is stubbed on purpose: only `compilerOptions` is wanted here,
+ * and letting TypeScript glob the config's `include` set would stat the user's
+ * whole project on every config discovered.
+ */
+const parseConfigHost: ts.ParseConfigHost = {
+    useCaseSensitiveFileNames: ts.sys?.useCaseSensitiveFileNames ?? true,
+    readDirectory: () => [],
+    fileExists: (fileName) => fs.existsSync(fileName),
+    readFile: (fileName) => {
+        try {
+            return fs.readFileSync(fileName, "utf8");
+        } catch (e) {
+            if (!(e as any)?.code) { throw e; }
+            return undefined;
+        }
+    },
+};
+
+function loadConfig(configFilePath: string): ResolvedConfig | null {
+    const { config, error } = ts.readConfigFile(configFilePath, parseConfigHost.readFile);
+    if (error) {
+        warnOnce(configFilePath,
+            `schema-codegen: could not read "${configFilePath}" ` +
+            `(${ts.flattenDiagnosticMessageText(error.messageText, " ")}) — ` +
+            `its import path aliases will be ignored.`);
+        return null;
+    }
+
+    // parseJsonConfigFileContent (not convertCompilerOptionsFromJson) is what
+    // applies `extends` chains, `${configDir}` templates, and `pathsBasePath` —
+    // the directory of the config that DECLARED `paths`, which in a monorepo is
+    // not the directory of the config being loaded.
+    const parsed = ts.parseJsonConfigFileContent(
+        config,
+        parseConfigHost,
+        path.dirname(configFilePath),
+        undefined,
+        configFilePath,
+    );
+
+    const errors = parsed.errors.filter((d) =>
+        d.code !== NO_INPUTS_FOUND && d.category === ts.DiagnosticCategory.Error);
+
+    if (errors.length > 0) {
+        warnOnce(configFilePath,
+            `schema-codegen: "${configFilePath}" has errors — ` +
+            errors.map((d) => ts.flattenDiagnosticMessageText(d.messageText, " ")).join("; "));
+    }
+
+    const options = parsed.options;
+    if (!options.paths && !options.baseUrl) { return null; }
+
+    const getCanonicalFileName = parseConfigHost.useCaseSensitiveFileNames
+        ? (f: string) => f
+        : (f: string) => f.toLowerCase();
+
+    return {
+        configFilePath,
+        options,
+        cache: ts.createModuleResolutionCache(
+            path.dirname(configFilePath), getCanonicalFileName, options),
+    };
+}
+
+function getOverrideConfig(): ResolvedConfig | null {
+    if (override === undefined) {
+        override = loadConfig(path.resolve(resolveOptions.tsconfig));
+        if (override === null) {
+            warnOnce(`no-aliases:${resolveOptions.tsconfig}`,
+                `schema-codegen: "${resolveOptions.tsconfig}" declares no "paths" or ` +
+                `"baseUrl" — there are no import aliases to resolve.`);
+        }
+    }
+    return override;
+}
+
+/**
+ * Nearest `tsconfig.json`/`jsconfig.json` above `containingFile`. Both names are
+ * checked at every level: a distant tsconfig.json must not win over an adjacent
+ * jsconfig.json. Stops at the first config found even when it declares no
+ * aliases — matching `tsc`, a parent project's `paths` do not leak into a child
+ * that does not `extends` it.
+ */
+function getConfigFor(containingFile: string): ResolvedConfig | null {
+    if (resolveOptions.tsconfig) { return getOverrideConfig(); }
+
+    const dir = path.dirname(containingFile);
+    if (configByDir.has(dir)) { return configByDir.get(dir); }
+
+    let config: ResolvedConfig | null = null;
+    const visited: string[] = [];
+
+    for (let current = dir, parent: string; ; current = parent) {
+        visited.push(current);
+
+        const found = CONFIG_NAMES
+            .map((name) => path.join(current, name))
+            .find((candidate) => fs.existsSync(candidate));
+
+        if (found) {
+            config = loadConfig(found);
+            break;
+        }
+
+        parent = path.dirname(current);
+        if (parent === current) { break; }
+    }
+
+    // memoize the whole walk, negatives included
+    visited.forEach((visitedDir) => configByDir.set(visitedDir, config));
+
+    return config;
+}
+
+/** Exact patterns win outright; among wildcards the longest prefix wins. */
+function findBestPathPattern(specifier: string, paths: ts.MapLike<string[]>): MatchedPattern | undefined {
+    let best: MatchedPattern | undefined;
+    let bestPrefixLength = -1;
+
+    for (const pattern in paths) {
+        const star = pattern.indexOf("*");
+
+        if (star === -1) {
+            if (pattern === specifier) {
+                return { substitutions: paths[pattern], matchedStar: "" };
+            }
+            continue;
+        }
+
+        const prefix = pattern.slice(0, star);
+        const suffix = pattern.slice(star + 1);
+
+        if (
+            specifier.length >= prefix.length + suffix.length &&
+            specifier.startsWith(prefix) &&
+            specifier.endsWith(suffix) &&
+            prefix.length > bestPrefixLength
+        ) {
+            bestPrefixLength = prefix.length;
+            best = {
+                substitutions: paths[pattern],
+                matchedStar: specifier.slice(prefix.length, specifier.length - suffix.length),
+            };
+        }
+    }
+
+    return best;
+}
+
+function resolveViaPathsSubstitution(matched: MatchedPattern, options: ts.CompilerOptions): string | undefined {
+    // mirrors ts.getPathsBasePath(): `paths` may be declared without a baseUrl,
+    // in which case it anchors on the config that declared it
+    const base = options.baseUrl ?? (options as any).pathsBasePath ?? process.cwd();
+
+    for (const substitution of matched.substitutions) {
+        const resolved = resolveSourceFile(
+            path.resolve(base, substitution.replace("*", matched.matchedStar)));
+        if (resolved) { return resolved; }
+    }
+
+    return undefined;
+}
+
+const isDeclaration = (fileName: string) => /\.d\.[cm]?ts$/.test(fileName);
+const isInNodeModules = (fileName: string) => fileName.replace(/\\/g, "/").includes("/node_modules/");
+
+/**
+ * Resolve a non-relative import (`@schemas/Player`, `shared/Player`) to a
+ * first-party source file through the tsconfig governing `containingFile`.
+ * Returns undefined for npm packages, declaration files, and specifiers no
+ * alias covers.
+ */
+export function resolveNonRelativeImport(specifier: string, containingFile: string): string | undefined {
+    const config = getConfigFor(containingFile);
+    if (!config) { return undefined; }
+
+    const { options } = config;
+    const matched = options.paths && findBestPathPattern(specifier, options.paths);
+
+    // no alias hit and no baseUrl: TypeScript could only find this under
+    // node_modules, which costs ~130 failed lookups to prove
+    if (!matched && !options.baseUrl) { return undefined; }
+
+    const resolved = ts.resolveModuleName(
+        specifier, containingFile, options, ts.sys, config.cache).resolvedModule;
+
+    if (resolved) {
+        // a deliberate package/typings hit — not ours to parse, and the
+        // substitution fallback must not second-guess it
+        return (
+            resolved.isExternalLibraryImport ||
+            isDeclaration(resolved.resolvedFileName) ||
+            isInNodeModules(resolved.resolvedFileName)
+        ) ? undefined
+          : path.resolve(resolved.resolvedFileName);
+    }
+
+    // `.mjs` targets are unresolvable by ts.resolveModuleName in every
+    // moduleResolution mode, but schema-codegen parses them
+    const viaSubstitution = matched && resolveViaPathsSubstitution(matched, options);
+    if (viaSubstitution) { return viaSubstitution; }
+
+    if (matched) {
+        warnOnce(`unresolved:${specifier}`,
+            `schema-codegen: '${specifier}' matches a "paths" alias in ` +
+            `${config.configFilePath}, but no source file was found for it — ` +
+            `schemas it exports will be missing from the generated output.`);
+    }
+
+    return undefined;
+}
+
+/** The extension alternatives parseFiles() probes, in order. Pure — no fs. */
+export function sourceFileCandidates(fileName: string): string[] {
+    if (
+        !fileName.endsWith(".ts") &&
+        !fileName.endsWith(".js") &&
+        !fileName.endsWith(".mjs")
+    ) {
+        return [`${fileName}.ts`, `${fileName}/index.ts`];
+
+    } else if (fileName.endsWith(".js")) {
+        // ESM imports often spell a .ts source with a .js extension
+        return [fileName, fileName.replace(/\.js$/, ".ts")];
+
+    } else {
+        return [fileName];
+    }
+}
+
+/** Same probing as parseFiles(), answering "which candidate exists?". */
+export function resolveSourceFile(fileName: string): string | undefined {
+    const candidates = sourceFileCandidates(fileName);
+
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = path.resolve(candidates[i]);
+        try {
+            // statSync, not existsSync: a directory must fall through to the
+            // next candidate, the way readFileSync's EISDIR does
+            if (fs.statSync(candidate).isFile()) { return candidate; }
+        } catch (e) {
+            if (!(e as any)?.code) { throw e; }
+        }
+    }
+
+    return undefined;
+}
+
+/**
+ * The serializer's own source declares wire-internal schemas (`Reflection`,
+ * `ReflectionField`, …) that must never reach generated client code.
+ */
+export function isOwnPackageSource(fileName: string): boolean {
+    const relative = path.relative(PACKAGE_ROOT, fileName);
+    return (
+        !relative.startsWith("..") &&
+        !path.isAbsolute(relative) &&
+        (relative.startsWith(`src${path.sep}`) || relative.startsWith(`build${path.sep}`))
+    );
+}

package/src/codegen/types.ts

@@ -5,7 +5,10 @@ if (typeof(__dirname) === "undefined") {
     global.__dirname = path.dirname(new URL(import.meta.url).pathname);
 }
 
-const VERSION = JSON.parse(fs.readFileSync(__dirname + "/../../package.json").toString()).version;
+/** Root of the @colyseus/schema package — `src/codegen/` in dev, `build/codegen/` once bundled. */
+export const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+
+const VERSION = JSON.parse(fs.readFileSync(path.resolve(PACKAGE_ROOT, "package.json")).toString()).version;
 const COMMENT_HEADER = `
 THIS FILE HAS BEEN GENERATED AUTOMATICALLY
 DO NOT CHANGE IT MANUALLY UNLESS YOU KNOW WHAT YOU'RE DOING

package/src/decoder/DecodeOperation.ts

@@ -240,7 +240,12 @@ export const decodeSchemaOperation: DecodeOperation = function <T extends Schema
         return DEFINITION_MISMATCH;
     }
 
-    const previousValue = ref[$getByIndex](index);
+    // a peer that still carries a @deprecated() field keeps sending it — the
+    // bytes must be consumed or the stream desyncs, but the local accessor
+    // may throw: read nothing, write nothing, report nothing.
+    const isDeprecated = field.deprecated === true;
+
+    const previousValue = isDeprecated ? undefined : ref[$getByIndex](index);
     const value = decodeValue(
         decoder,
         operation,
@@ -253,6 +258,8 @@ export const decodeSchemaOperation: DecodeOperation = function <T extends Schema
         allChanges,
     );
 
+    if (isDeprecated) { return; }
+
     if (value !== null && value !== undefined) {
         // Write via the generated setter. Bypass to `(ref as any)[$values][index]`
         // was attempted but only works for @type-decorated classes (which
@@ -430,7 +437,11 @@ export const decodeArray: DecodeOperation = function (
         return;
 
     } else if (operation === OPERATION.REVERSE) {
-        tgt.reverse();
+        // Positional reverse of the decoder's authoritative storage. Don't
+        // call `tgt.reverse()` — that's the encoder-side method, and its
+        // dirty-tick check would misread the stale recorder a `clone(true)`
+        // instance carries.
+        tgt.items.reverse();
         return;
 
     } else if (operation === OPERATION.DELETE_BY_REFID) {

package/src/decoder/strategy/Callbacks.ts

@@ -1,5 +1,5 @@
 import { Metadata } from "../../Metadata.js";
-import { Collection, NonFunctionPropNames } from "../../types/HelperTypes.js";
+import { Collection, NonFunctionPropNames, CollectionLike } from "../../types/HelperTypes.js";
 import type { IRef, Ref } from "../../encoder/ChangeTree.js";
 import { Decoder } from "../Decoder.js";
 import { DataChange } from "../DecodeOperation.js";
@@ -25,25 +25,24 @@ type KeyValueCallback<K, V> = (key: K, value: V) => void;
 type ValueKeyCallback<V, K> = (value: V, key: K) => void;
 type InstanceChangeCallback = () => void;
 
-// Exclude internal properties from valid property names
-type PublicPropNames<T> = Exclude<NonFunctionPropNames<T>, typeof $refId> & string;
+type PublicPropNames<T> = NonFunctionPropNames<T> & string;
 
 // Extract only properties that extend Collection
-type CollectionPropNames<T> = Exclude<{
-    [K in keyof T]: T[K] extends Collection<any, any> ? K : never
-}[keyof T] & string, typeof $refId>;
+type CollectionPropNames<T> = {
+    [K in keyof T]: T[K] extends CollectionLike<any, any> ? K : never
+}[keyof T] & string;
 
 // Infer the value type of a collection property
 type CollectionValueType<T, K extends keyof T> =
     T[K] extends MapSchema<infer V, any> ? V :
     T[K] extends ArraySchema<infer V> ? V :
-    T[K] extends Collection<any, infer V, any> ? V : never;
+    T[K] extends CollectionLike<any, infer V, any> ? V : never;
 
 // Infer the key type of a collection property
 type CollectionKeyType<T, K extends keyof T> =
     T[K] extends MapSchema<any, infer Key> ? Key :
     T[K] extends ArraySchema<any> ? number :
-    T[K] extends Collection<infer Key, any, any> ? Key : never;
+    T[K] extends CollectionLike<infer Key, any, any> ? Key : never;
 
 export class StateCallbackStrategy<TState extends IRef> {
     protected decoder: Decoder<TState>;

package/src/decoder/strategy/getDecoderStateCallbacks.ts

@@ -1,5 +1,5 @@
 import { Metadata } from "../../Metadata.js";
-import { Collection, NonFunctionNonPrimitivePropNames, NonFunctionPropNames } from "../../types/HelperTypes.js";
+import { Collection, NonFunctionNonPrimitivePropNames, NonFunctionPropNames, CollectionLike } from "../../types/HelperTypes.js";
 import { IRef, Ref } from "../../encoder/ChangeTree.js";
 import { Decoder } from "../Decoder.js";
 import { DataChange } from "../DecodeOperation.js";
@@ -30,7 +30,7 @@ export type GetCallbackProxy = SchemaCallbackProxy<any>; // workaround for compa
 
 export type CallbackProxy<T> = unknown extends T // is "any"?
     ? SchemaCallback<T> & CollectionCallback<any, any>
-    : T extends Collection<infer K, infer V, infer _>
+    : T extends CollectionLike<infer K, infer V, infer _>
         ? CollectionCallback<K, V>
         : SchemaCallback<T>;