@liautaud/typezod 1.0.1 → 2.0.0

package/README.md

@@ -27,7 +27,7 @@ const Rectangle = t.object({
   height: t.number(),
 });
 
-const ElectronWindow = t.fromModule("/electron/", "BaseWindow");
+const ElectronWindow = t.fromModule("electron", "BaseWindow");
 
 // Inside a typescript-eslint rule's `create()` function, build a context
 // from the parser services and use `isAssignableTo` to check types.
@@ -51,36 +51,55 @@ by the schema.
 ### `SchemaContext`
 
 The context object passed to `isAssignableTo`. Contains a `checker`
-(required) and an optional `program` (only needed for `t.fromModule()`).
+(always required), a `program` (required when using `t.fromModule()`),
+and a `sourceFile` (required when using `t.fromModule()` with a relative
+module specifier such as `"./foo"` or `"../foo"`).
+
+Example for relative module specifiers inside an ESLint rule:
+
+```typescript
+const tsNode = parserServices.esTreeNodeToTSNodeMap.get(node);
+const ctx: SchemaContext = {
+  checker: parserServices.program.getTypeChecker(),
+  program: parserServices.program,
+  sourceFile: tsNode.getSourceFile(),
+};
+```
 
 ### Primitives
 
-| Builder          | Description                    |
-| ---------------- | ------------------------------ |
-| `t.string()`     | Represents the `string` type   |
-| `t.number()`     | Represents the `number` type   |
-| `t.boolean()`    | Represents the `boolean` type  |
-| `t.void()`       | Represents the `void` type     |
-| `t.undefined()`  | Represents the `undefined` type|
-| `t.null()`       | Represents the `null` type     |
-| `t.any()`        | Accepts any type               |
-| `t.unknown()`    | Accepts any type               |
+| Builder         | Description                     |
+| --------------- | ------------------------------- |
+| `t.string()`    | Represents the `string` type    |
+| `t.number()`    | Represents the `number` type    |
+| `t.boolean()`   | Represents the `boolean` type   |
+| `t.void()`      | Represents the `void` type      |
+| `t.undefined()` | Represents the `undefined` type |
+| `t.null()`      | Represents the `null` type      |
+| `t.any()`       | Accepts any type                |
+| `t.unknown()`   | Accepts any type                |
 
 ### Combinators
 
-| Builder                    | Description                                                      |
-| -------------------------- | ---------------------------------------------------------------- |
-| `t.object(shape)`          | Represents an object with the given shape (structural subtyping) |
-| `t.array(element)`         | Represents an array whose element satisfies the given schema     |
-| `t.union(...schemas)`      | Represents a union of the given schemas                          |
-| `t.intersection(...schemas)` | Represents an intersection of the given schemas                |
+| Builder                      | Description                                                      |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `t.object(shape)`            | Represents an object with the given shape (structural subtyping) |
+| `t.array(element)`           | Represents an array whose element satisfies the given schema     |
+| `t.union(...schemas)`        | Represents a union of the given schemas                          |
+| `t.intersection(...schemas)` | Represents an intersection of the given schemas                  |
 
 ### Advanced
 
-| Builder                                 | Description                                             |
-| --------------------------------------- | ------------------------------------------------------- |
-| `t.fromModule(pathPattern, exportName)` | Represents a type exported from a module in the program |
-| `t.custom(fn)`                          | Escape hatch for arbitrary predicates                   |
+| Builder                                | Description                                             |
+| -------------------------------------- | ------------------------------------------------------- |
+| `t.fromModule(moduleName, exportName)` | Represents a type exported from a module in the program |
+| `t.custom(fn)`                         | Escape hatch for arbitrary predicates                   |
+
+`t.fromModule()` accepts the same module specifier you'd write in an `import` statement.
+Installed packages (`"typescript"`, `"electron"`), relative paths (`"./types"`,
+`"../shared/types"`), and ambient module declarations (`declare module '...'`) are
+all supported. Relative specifiers require `sourceFile` in the context. Throws if the
+module or export cannot be found.
 
 ### Modifiers
 

package/dist/index.d.mts

@@ -1,14 +1,21 @@
-import { Program, Type, TypeChecker } from "typescript";
+import { Program, SourceFile, Type, TypeChecker } from "typescript";
 
 //#region src/index.d.ts
 
 /**
- * Context required by all schema checks. The `program` field is only needed
- * for schemas that resolve types from external modules ({@link t.fromModule}).
+ * Context required by all schema checks.
+ *
+ * `program` is required by schemas that resolve module exports
+ * ({@link t.fromModule}).
+ *
+ * `sourceFile` is only required when resolving relative module specifiers
+ * (`"./x"`, `"../x"`) with {@link t.fromModule}. It should be the source file
+ * currently being analyzed.
  */
 type SchemaContext = {
   checker: TypeChecker;
   program?: Program;
+  sourceFile?: SourceFile;
 };
 type AcceptsFn = (type: Type, ctx: SchemaContext) => boolean;
 /**
@@ -56,6 +63,12 @@ declare class TypeSchema {
    */
   nullish(): TypeSchema;
 }
+/**
+ * Returns `true` if the given TypeScript type is assignable to the schema–in
+ * other words, if `type extends T` with `T` the TypeScript type represented
+ * by the schema.
+ */
+declare function isAssignableTo(ctx: SchemaContext, type: Type, schema: TypeSchema): boolean;
 /**
  * Schema builder namespace.
  */
@@ -134,25 +147,27 @@ declare const t: {
    */
   intersection: (...members: TypeSchema[]) => TypeSchema;
   /**
-   * Represents a type exported from a module in the program. Resolves a genuine
-   * `ts.Type` and delegates to `checker.isTypeAssignableTo()`, so it handles
-   * nominal class hierarchies correctly.
+   * Represents a type exported from a module. Resolves the module using
+   * TypeScript's module resolution algorithm, with a fallback to ambient
+   * module declarations. Resolved types are cached per `TypeChecker` instance.
    *
-   * Resolved types are cached per `TypeChecker` instance (via a `WeakMap`) so
-   * repeated calls across files do not re-scan source files.
+   * Requires `program` in the {@link SchemaContext}. Relative specifiers
+   * (`"./x"`, `"../x"`) also require `sourceFile`.
    *
-   * Requires `program` in the {@link SchemaContext}.
-   *
-   * @param modulePathPattern Substring matched against source-file paths.
+   * @param moduleName The module specifier, as in an `import` statement.
    * @param exportName The exported type, class or interface name.
    *
    * @example
    * ```typescript
-   * const BaseWindow = t.fromModule("/electron/", "BaseWindow");
-   * const Buffer = t.fromModule("@types/node", "Buffer");
+   * const BaseWindow = t.fromModule("electron", "BaseWindow");
+   * const Buffer = t.fromModule("node:buffer", "Buffer");
    * ```
+   *
+   * @throws When `program` is missing from the context.
+   * @throws When `moduleName` is relative and `sourceFile` is missing.
+   * @throws When no export named `exportName` can be resolved from `moduleName`.
    */
-  fromModule: (modulePathPattern: string, exportName: string) => TypeSchema;
+  fromModule: (moduleName: string, exportName: string) => TypeSchema;
   /**
    * Escape hatch for arbitrary predicates that the DSL cannot express directly.
    *
@@ -165,11 +180,5 @@ declare const t: {
    */
   custom: (predicate: AcceptsFn) => TypeSchema;
 };
-/**
- * Returns `true` if the given TypeScript type is assignable to the schema–in
- * other words, if `type extends T` with `T` the TypeScript type represented
- * by the schema.
- */
-declare function isAssignableTo(ctx: SchemaContext, type: Type, schema: TypeSchema): boolean;
 //#endregion
 export { SchemaContext, TypeSchema, isAssignableTo, t };

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import ts from "typescript";
+
 //#region src/index.ts
 const TS_SYMBOL_FLAGS_OPTIONAL = 16777216;
 /**
@@ -55,7 +57,14 @@ var TypeSchema = class TypeSchema {
 	}
 };
 const schema = (check) => new TypeSchema(check);
-const moduleTypeCache = /* @__PURE__ */ new WeakMap();
+/**
+* Returns `true` if the given TypeScript type is assignable to the schema–in
+* other words, if `type extends T` with `T` the TypeScript type represented
+* by the schema.
+*/
+function isAssignableTo(ctx, type, schema$1) {
+	return schema$1._accepts(type, ctx);
+}
 /**
 * Schema builder namespace.
 */
@@ -85,42 +94,56 @@ const t = {
 		return members.some((m) => m._accepts(type, ctx));
 	}),
 	intersection: (...members) => schema((type, ctx) => members.every((m) => m._accepts(type, ctx))),
-	fromModule: (modulePathPattern, exportName) => schema((type, { checker, program }) => {
+	fromModule: (moduleName, exportName) => schema((type, { checker, program, sourceFile }) => {
 		if (!program) throw new Error("t.fromModule() requires `program` in the SchemaContext.");
+		const isRelative = moduleName.startsWith("./") || moduleName.startsWith("../");
+		if (isRelative && !sourceFile) throw new Error("t.fromModule() requires `sourceFile` in the SchemaContext for relative module specifiers.");
 		let cache = moduleTypeCache.get(checker);
 		if (!cache) {
 			cache = /* @__PURE__ */ new Map();
 			moduleTypeCache.set(checker, cache);
 		}
-		const cacheKey = JSON.stringify([modulePathPattern, exportName]);
-		if (!cache.has(cacheKey)) {
-			let resolved = null;
-			for (const sourceFile of program.getSourceFiles()) {
-				if (!sourceFile.fileName.includes(modulePathPattern)) continue;
-				const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
-				if (!moduleSymbol) continue;
-				const exportSymbol = checker.getExportsOfModule(moduleSymbol).find((s) => s.getName() === exportName);
-				if (exportSymbol) {
-					resolved = checker.getDeclaredTypeOfSymbol(exportSymbol);
-					break;
-				}
-			}
-			cache.set(cacheKey, resolved);
-		}
+		const cacheKey = JSON.stringify([
+			moduleName,
+			exportName,
+			isRelative ? sourceFile.fileName : null
+		]);
+		if (!cache.has(cacheKey)) cache.set(cacheKey, resolveModuleType(checker, program, moduleName, exportName, sourceFile));
 		const targetType = cache.get(cacheKey);
-		if (targetType == null) throw new Error(`t.fromModule(): could not resolve export "${exportName}" from any module matching "${modulePathPattern}".`);
+		if (targetType == null) throw new Error(`t.fromModule(): could not resolve export "${exportName}" from module "${moduleName}".`);
 		return checker.isTypeAssignableTo(type, targetType);
 	}),
 	custom: (predicate) => schema(predicate)
 };
+/** Per-checker cache for `t.fromModule()` resolved types. */
+const moduleTypeCache = /* @__PURE__ */ new WeakMap();
 /**
-* Returns `true` if the given TypeScript type is assignable to the schema–in
-* other words, if `type extends T` with `T` the TypeScript type represented
-* by the schema.
+* Resolves a module's exported type using TypeScript's module resolution
+* algorithm, with a fallback to ambient module declarations.
+*
+* Returns the resolved `ts.Type`, or `null` if the export cannot be found.
+*
+* @throws When multiple ambient/resolved symbols yield different types for the
+* same export name (ambiguity).
 */
-function isAssignableTo(ctx, type, schema$1) {
-	return schema$1._accepts(type, ctx);
-}
+const resolveModuleType = (checker, program, moduleName, exportName, sourceFile) => {
+	const compilerOptions = program.getCompilerOptions();
+	const containingFile = sourceFile ? sourceFile.fileName : program.getCurrentDirectory() + "/__typezod__.ts";
+	let moduleSymbol;
+	const resolved = ts.resolveModuleName(moduleName, containingFile, compilerOptions, ts.sys);
+	if (resolved.resolvedModule) {
+		const resolvedSf = program.getSourceFile(resolved.resolvedModule.resolvedFileName);
+		if (resolvedSf) moduleSymbol = checker.getSymbolAtLocation(resolvedSf);
+	}
+	if (!moduleSymbol) {
+		const quotedName = `"${moduleName}"`;
+		moduleSymbol = checker.getAmbientModules().find((s) => s.getName() === quotedName);
+	}
+	if (!moduleSymbol) return null;
+	const exportSymbol = checker.getExportsOfModule(moduleSymbol).find((s) => s.getName() === exportName);
+	if (!exportSymbol) return null;
+	return checker.getDeclaredTypeOfSymbol(exportSymbol);
+};
 
 //#endregion
 export { TypeSchema, isAssignableTo, t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@liautaud/typezod",
   "type": "module",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Zod-like DSL for comparing TypeScript compiler types against user-defined schemas",
   "author": "Romain Liautaud",
   "license": "MIT",