@colyseus/schema 5.0.13 → 5.0.19

package/build/types/HelperTypes.d.ts

@@ -70,7 +70,7 @@ export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : 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;
 type OptionalBuilderKeys<T> = {
-    [K in keyof T]: T[K] extends FieldBuilder<infer V> ? (undefined extends V ? K : never) : never;
+    [K in keyof T]: T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean> ? (O extends true ? K : never) : never;
 }[keyof T];
 type RequiredBuilderKeys<T> = Exclude<keyof T, OptionalBuilderKeys<T>>;
 export type InferSchemaInstanceType<T> = {
@@ -89,12 +89,10 @@ export type NonFunctionNonPrimitivePropNames<T> = {
 }[keyof 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 ToJSONRequiredKeys<T> = {
-    [K in keyof T]-?: undefined extends T[K] ? never : K;
-}[keyof T];
 type ToJSONOptionalKeys<T> = {
-    [K in keyof T]-?: undefined extends T[K] ? K : never;
+    [K in keyof T]-?: undefined extends {} ? ({} extends Pick<T, K> ? K : never) : (undefined extends T[K] ? K : never);
 }[keyof T];
+type ToJSONRequiredKeys<T> = Exclude<keyof T, ToJSONOptionalKeys<T>>;
 export type ToJSON<T> = NonFunctionProps<{
     [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]>;
 } & {

package/build/types/TypeContext.d.ts

@@ -5,18 +5,6 @@ export declare class TypeContext {
     };
     schemas: Map<typeof Schema, number>;
     hasFilters: boolean;
-    parentFiltered: {
-        [typeIdAndParentIndex: string]: boolean;
-    };
-    /**
-     * True iff `parentFiltered` has at least one entry. Flipped on by
-     * `registerFilteredByParent` and read in `checkInheritedFlags` as a
-     * cheap gate to skip the string-keyed `parentFiltered[key]` lookup
-     * when no class has registered filter inheritance via ancestry — the
-     * common case when @view tags exist only on sibling fields, not
-     * along any attachment chain.
-     */
-    hasParentFilteredEntries: boolean;
     /**
      * For inheritance support
      * Keeps track of which classes extends which. (parent -> children)
@@ -31,10 +19,5 @@ export declare class TypeContext {
     add(schema: typeof Schema, typeid?: number): boolean;
     getTypeId(klass: typeof Schema): number;
     private discoverTypes;
-    /**
-     * Keep track of which classes have filters applied.
-     * Format: `${typeid}-${parentTypeid}-${parentIndex}`
-     */
-    private registerFilteredByParent;
     debug(): string;
 }

package/build/types/builder.d.ts

@@ -45,10 +45,11 @@ export type BuilderOf<T> = FieldBuilder<T>;
  *    Schema ref whose `initialize` takes zero args.
  *  - `IsOptional` is a compile-time brand for `.optional()`. Both
  *    `HasDefault` and `IsOptional` make the field omittable in
- *    `BuilderInitProps<T>`. A separate brand (rather than reading
- *    `undefined extends V`) sidesteps a TypeScript quirk where
- *    class-generic-inferred `V` resolves `undefined extends V` as `true`
- *    even for non-undefined types.
+ *    `BuilderInitProps<T>`; `IsOptional` alone marks the instance property
+ *    `?:`. A separate brand (rather than reading `undefined extends V`)
+ *    keeps both correct for consumers compiling with
+ *    `strictNullChecks: false`, where `undefined extends V` is true for
+ *    every V.
  *
  * schema() reads the internal configuration via `toDefinition()` and wires
  * up metadata through the existing pipeline.
@@ -199,8 +200,8 @@ export declare function isBuilder(value: any): value is FieldBuilder<any>;
  * Two call signatures, NOT a defaulted generic `<T extends TBase = TBase>`: the
  * bare form must return a CONCRETE `FieldBuilder<TBase>` so `schema({ x:
  * t.number() })` still infers `x: number`. A defaulted free type parameter gets
- * captured as `any` during `schema()`'s self-referential field inference (and
- * `undefined extends any` then flips every field optional).
+ * captured as `any` during `schema()`'s self-referential field inference,
+ * degrading every field's value type to `any`.
  *
  * NOTE: the refinement is a TYPE-LEVEL assertion, not a runtime guarantee — the
  * wire still carries the codec's full range and the DECODER writes whatever
@@ -212,26 +213,22 @@ interface PrimitiveFactory<TBase> {
     (): FieldBuilder<TBase>;
     <T extends TBase>(): FieldBuilder<T>;
 }
-export type ChildType = RawPrimitiveType | Constructor<Schema> | FieldBuilder<any>;
+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>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<ArraySchema<V>, 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>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<MapSchema<V>, 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>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<SetSchema<V>, 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>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<CollectionSchema<V>, true, false>;
 }
 interface StreamFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<StreamSchema<InstanceType<C>>, true, false>;

package/build/types/symbols.d.ts

@@ -80,6 +80,7 @@ export declare const $viewFieldIndexes = "~__viewFieldIndexes";
 export declare const $fieldIndexesByViewTag = "$__fieldIndexesByViewTag";
 export declare const $unreliableFieldIndexes = "~__unreliableFieldIndexes";
 export declare const $patchOnlyFieldIndexes = "~__patchOnlyFieldIndexes";
+export declare const $fullSyncSkipIndexes = "~__fullSyncSkipIndexes";
 export declare const $fullStateOnlyFieldIndexes = "~__fullStateOnlyFieldIndexes";
 export declare const $streamFieldIndexes = "~__streamFieldIndexes";
 export declare const $streamPriorities = "~__streamPriorities";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.13",
+  "version": "5.0.19",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
     "watch": "tsc -p tsconfig.build.json -w",
     "typecheck:build": "tsc -p tsconfig.build.json --noEmit",
     "test": "npm run test:types && tsx --tsconfig tsconfig.test.json ./node_modules/mocha/bin/mocha.js \"test/*.test.ts\" \"test/**/*.test.ts\"",
-    "test:types": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
+    "test:types": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json && tsc -p tsconfig.types-nostrict.json",
     "test:exports": "node test/verify-exports.mjs",
     "typecheck": "tsc -p tsconfig.test.json",
     "coverage": "c8 npm run test",

package/src/Metadata.ts

@@ -1,7 +1,7 @@
 import { DefinitionType, getPropertyDescriptor } from "./annotations.js";
 import { Schema } from "./Schema.js";
 import { getType, registeredTypes, TypeDefinition } from "./types/registry.js";
-import { $decoder, $descriptors, $encoder, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $fullStateOnlyFieldIndexes, $streamFieldIndexes, $streamPriorities, $track, $patchOnlyFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
+import { $decoder, $descriptors, $encoder, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $fullStateOnlyFieldIndexes, $fullSyncSkipIndexes, $streamFieldIndexes, $streamPriorities, $track, $patchOnlyFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
 import { ARRAY_STREAM_NOT_SUPPORTED } from "./encoder/streaming.js";
 import { encode } from "./encoding/encode.js";
 import { TypeContext } from "./types/TypeContext.js";
@@ -37,6 +37,8 @@ export type Metadata =
     { [$refTypeFieldIndexes]: number[]; } & // all field indexes containing Ref types (Schema, ArraySchema, MapSchema, etc)
     { [$unreliableFieldIndexes]: number[]; } & // all field indexes tagged with @unreliable
     { [$patchOnlyFieldIndexes]: number[]; } & // all field indexes tagged with @patchOnly (not persisted to snapshots)
+    { [$fullSyncSkipIndexes]: number[]; } & // @patchOnly ∪ @deprecated() — never read during full sync
+
     { [$fullStateOnlyFieldIndexes]: number[]; } & // all field indexes tagged @fullStateOnly / .fullStateOnly() (not tracked after assignment)
     { [$streamFieldIndexes]: number[]; } & // all field indexes holding a t.stream(...) collection
     { [$streamPriorities]: { [field: number]: (view: any, element: any) => number }; } & // per-stream-field priority callback declared at schema definition time
@@ -113,6 +115,30 @@ function isTSEnum(_enum: any) {
     return false;
 }
 
+// Copied parent → subclass on Metadata.initialize, so each class owns its list.
+const INHERITED_ARRAY_KEYS = [
+    $refTypeFieldIndexes,
+    $unreliableFieldIndexes,
+    $patchOnlyFieldIndexes,
+    $fullSyncSkipIndexes,
+    $fullStateOnlyFieldIndexes,
+    $streamFieldIndexes,
+    $encoders,
+];
+
+/** Append to a non-enumerable metadata index list, creating it on first use. */
+function pushIndexList(metadata: any, key: string, index: number) {
+    if (!metadata[key]) {
+        Object.defineProperty(metadata, key, {
+            value: [],
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+    }
+    metadata[key].push(index);
+}
+
 export const Metadata = {
 
     addField(metadata: any, index: number, name: string, type: DefinitionType, descriptor?: PropertyDescriptor) {
@@ -302,15 +328,26 @@ export const Metadata = {
         }
         metadata[index].patchOnly = true;
 
-        if (!metadata[$patchOnlyFieldIndexes]) {
-            Object.defineProperty(metadata, $patchOnlyFieldIndexes, {
-                value: [],
-                enumerable: false,
-                configurable: true,
-                writable: true,
-            });
-        }
-        metadata[$patchOnlyFieldIndexes].push(index);
+        pushIndexList(metadata, $patchOnlyFieldIndexes, index);
+        pushIndexList(metadata, $fullSyncSkipIndexes, index); // not persisted to snapshots
+    },
+
+    /**
+     * `@deprecated()` bookkeeping: the field keeps its wire index (so peers
+     * that still carry it stay compatible) but is excluded from full sync —
+     * its accessor may throw — and hidden from `for..in` consumers.
+     */
+    setDeprecated(metadata: Metadata, fieldName: string) {
+        const index = metadata[fieldName];
+        metadata[index].deprecated = true;
+
+        pushIndexList(metadata, $fullSyncSkipIndexes, index);
+
+        Object.defineProperty(metadata, index, {
+            value: metadata[index],
+            enumerable: false,
+            configurable: true
+        });
     },
 
     setFullStateOnly(metadata: Metadata, fieldName: string) {
@@ -324,15 +361,7 @@ export const Metadata = {
         }
         metadata[index].fullStateOnly = true;
 
-        if (!metadata[$fullStateOnlyFieldIndexes]) {
-            Object.defineProperty(metadata, $fullStateOnlyFieldIndexes, {
-                value: [],
-                enumerable: false,
-                configurable: true,
-                writable: true,
-            });
-        }
-        metadata[$fullStateOnlyFieldIndexes].push(index);
+        pushIndexList(metadata, $fullStateOnlyFieldIndexes, index);
     },
 
     setStream(metadata: Metadata, fieldName: string) {
@@ -510,54 +539,17 @@ export const Metadata = {
                     });
                 }
 
-                // $refTypeFieldIndexes
-                if (parentMetadata[$refTypeFieldIndexes] !== undefined) {
-                    Object.defineProperty(metadata, $refTypeFieldIndexes, {
-                        value: [...parentMetadata[$refTypeFieldIndexes]],
-                        enumerable: false,
-                        configurable: true,
-                        writable: true,
-                    });
-                }
-
-                // $unreliableFieldIndexes
-                if (parentMetadata[$unreliableFieldIndexes] !== undefined) {
-                    Object.defineProperty(metadata, $unreliableFieldIndexes, {
-                        value: [...parentMetadata[$unreliableFieldIndexes]],
-                        enumerable: false,
-                        configurable: true,
-                        writable: true,
-                    });
-                }
-
-                // $patchOnlyFieldIndexes
-                if (parentMetadata[$patchOnlyFieldIndexes] !== undefined) {
-                    Object.defineProperty(metadata, $patchOnlyFieldIndexes, {
-                        value: [...parentMetadata[$patchOnlyFieldIndexes]],
-                        enumerable: false,
-                        configurable: true,
-                        writable: true,
-                    });
-                }
-
-                // $fullStateOnlyFieldIndexes
-                if (parentMetadata[$fullStateOnlyFieldIndexes] !== undefined) {
-                    Object.defineProperty(metadata, $fullStateOnlyFieldIndexes, {
-                        value: [...parentMetadata[$fullStateOnlyFieldIndexes]],
-                        enumerable: false,
-                        configurable: true,
-                        writable: true,
-                    });
-                }
-
-                // $streamFieldIndexes
-                if (parentMetadata[$streamFieldIndexes] !== undefined) {
-                    Object.defineProperty(metadata, $streamFieldIndexes, {
-                        value: [...parentMetadata[$streamFieldIndexes]],
-                        enumerable: false,
-                        configurable: true,
-                        writable: true,
-                    });
+                // per-class arrays the subclass extends independently
+                for (const key of INHERITED_ARRAY_KEYS) {
+                    const list = parentMetadata[key] as unknown as any[] | undefined;
+                    if (list !== undefined) {
+                        Object.defineProperty(metadata, key, {
+                            value: [...list],
+                            enumerable: false,
+                            configurable: true,
+                            writable: true,
+                        });
+                    }
                 }
 
                 // $descriptors
@@ -567,16 +559,6 @@ export const Metadata = {
                     configurable: true,
                     writable: true,
                 });
-
-                // $encoders
-                if (parentMetadata[$encoders] !== undefined) {
-                    Object.defineProperty(metadata, $encoders, {
-                        value: [...parentMetadata[$encoders]],
-                        enumerable: false,
-                        configurable: true,
-                        writable: true,
-                    });
-                }
             }
         }
 

package/src/Reflection.ts

@@ -149,9 +149,15 @@ Reflection.encode = function (encoder: Encoder, it: Iterator = { offset: 0 }) {
         // if metadata is the same reference as the parent class - it means the class has no own metadata
         //
         if (metadata !== inheritFrom[Symbol.metadata]) {
-            for (const fieldIndex in metadata) {
-                const index = Number(fieldIndex);
-                const fieldName = metadata[index].name;
+            // Walk by index rather than `for…in`: `@deprecated()` makes its
+            // metadata slot non-enumerable, and dropping it from the payload
+            // shifts every later field down one wire index on the peer.
+            const numFields = (metadata[$numFields] ?? -1) as number;
+            for (let index = 0; index <= numFields; index++) {
+                const field = metadata[index];
+                if (field === undefined) { continue; }
+
+                const fieldName = field.name;
 
                 // skip fields from parent classes
                 if (!Object.prototype.hasOwnProperty.call(metadata, fieldName)) {
@@ -163,8 +169,6 @@ Reflection.encode = function (encoder: Encoder, it: Iterator = { offset: 0 }) {
 
                 let fieldType: string;
 
-                const field = metadata[index];
-
                 if (typeof (field.type) === "string") {
                     fieldType = field.type;
 

package/src/annotations.ts

@@ -477,12 +477,27 @@ function makeCollectionSetter(
 
         if (value !== undefined && value !== null) {
             // automatic Array → ArraySchema / Map → MapSchema conversion.
+            // `$childType` goes on before populating — push()/set() gate
+            // their `assertInstanceType` on it.
             if (isArrayKlass && !(value instanceof ArraySchema)) {
-                value = new ArraySchema(...value);
+                const array: any = new ArraySchema();
+                array[$childType] = type;
+                array.push(...value);
+                value = array;
+
             } else if (isMapKlass && !(value instanceof MapSchema)) {
-                value = new MapSchema(value);
+                const map: any = new MapSchema();
+                map[$childType] = type;
+                if (value instanceof Map) {
+                    value.forEach((v, k) => map.set(k, v));
+                } else {
+                    for (const k in value) { map.set(k, value[k]); }
+                }
+                value = map;
+
+            } else {
+                value[$childType] = type;
             }
-            value[$childType] = type;
 
             const changeTree = this[$changes];
             const ctor = this.constructor as typeof Schema;
@@ -569,9 +584,7 @@ export function getPropertyDescriptor(
 export function deprecated(throws: boolean = true): PropertyDecorator {
     return function (klass: typeof Schema, field: string) {
         const metadata = Metadata.initialize(klass.constructor as typeof Schema);
-        const fieldIndex = metadata[field];
-
-        metadata[fieldIndex].deprecated = true;
+        Metadata.setDeprecated(metadata, field);
 
         if (throws) {
             metadata[$descriptors] ??= {};
@@ -584,13 +597,6 @@ export function deprecated(throws: boolean = true): PropertyDecorator {
             // Override accessor on the prototype so deprecated throws at access.
             Object.defineProperty(klass, field, metadata[$descriptors][field]);
         }
-
-        // flag metadata[field] as non-enumerable
-        Object.defineProperty(metadata, fieldIndex, {
-            value: metadata[fieldIndex],
-            enumerable: false,
-            configurable: true
-        });
     }
 }
 

package/src/codegen/api.ts

@@ -24,6 +24,8 @@ export interface GenerateOptions {
     decorator?: string;
     namespace?: string;
     bundle?: boolean;
+    /** Overrides the nearest-tsconfig lookup used to resolve import path aliases. */
+    tsconfig?: string;
 }
 
 export function generate(targetId: string, options: GenerateOptions) {
@@ -53,7 +55,7 @@ export function generate(targetId: string, options: GenerateOptions) {
         return acc;
     }, [])
 
-    const structures = parseFiles(options.files, options.decorator);
+    const structures = parseFiles(options.files, options.decorator, undefined, { tsconfig: options.tsconfig });
 
     // Post-process classes before generating
     structures.classes.forEach(klass => klass.postProcessing());

package/src/codegen/cli.ts

@@ -21,7 +21,9 @@ ${Object.
 
 Optional:
     --namespace: generate namespace on output code
-    --decorator: custom name for @type decorator to scan for`);
+    --decorator: custom name for @type decorator to scan for
+    --tsconfig: tsconfig.json to resolve import path aliases with
+                (default: nearest tsconfig.json/jsconfig.json above each source file)`);
     process.exit(exitCode);
 }
 
@@ -49,7 +51,8 @@ try {
         decorator: args.decorator,
         output: args.output,
         namespace: args.namespace,
-        bundle: args.bundle
+        bundle: args.bundle,
+        tsconfig: args.tsconfig,
     });
 
 } catch (e) {

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 {