diff --git a/typescript/README.md b/typescript/README.md index 3b8f934a..171f378a 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -27,6 +27,30 @@ Install TypeChat: npm install typechat ``` +TypeChat supports both native ECMAScript modules (ESM) and CommonJS. Use `import` +in an ESM application: + +```js +import { createJsonTranslator } from "typechat"; +import { createTypeScriptJsonValidator } from "typechat/ts"; +``` + +Or use `require` in a CommonJS application: + +```js +const { createJsonTranslator } = require("typechat"); +const { createTypeScriptJsonValidator } = require("typechat/ts"); +``` + +The `typechat`, `typechat/ts`, `typechat/zod`, and `typechat/interactive` entry points +select the matching JavaScript build and TypeScript declarations automatically. +Both builds target ES2021 and require Node.js 24.22.1 or newer. + +For compatibility with earlier CommonJS-only releases, native ESM default imports +(`import typechat from "typechat"`) and dynamic imports' `.default` properties remain +supported for all four entry points. Default imports also preserve the exported +TypeScript types, such as `typechat.Result`. + You can also build TypeChat from source: ```sh @@ -36,9 +60,14 @@ npm install npm run build ``` -Run the test suite with `npm test`. It builds the library, compiles TypeScript tests, -and recursively discovers compiled `*.test.js` suites under `out/` and runtime -`*.test.mjs` suites under `tests/`. Add TypeScript tests under +The build emits CommonJS JavaScript and declarations in `dist`, and native ESM +JavaScript and declarations in `dist/esm`. + +Run the test suite with `npm test`. Package tests verify named and default imports, +both module formats, and their declaration resolution using only the files included +in the npm package. +The test command recursively discovers compiled `*.test.js` suites under `out/` +and runtime `*.test.mjs` suites under `tests/`. Add TypeScript tests under [test/](https://github.com/microsoft/TypeChat/tree/main/typescript/test) or runtime tests under [tests/](https://github.com/microsoft/TypeChat/tree/main/typescript/tests); no manual suite-list update is needed. @@ -59,6 +88,9 @@ validation and repair flow. Zod and custom validators without schema-only checks their existing instance-validation behavior. The `TypeChatJsonValidator` contract is unchanged; custom validators can opt in through the exported `typeChatSchemaValidation` symbol, so existing string-named `validateSchema` methods are not invoked as preflight. +The symbol's runtime value and canonical declaration are shared across the ESM and +CommonJS builds, so validators remain type-compatible and schema preflight also runs +when a validator and translator come from different module formats. To see TypeChat in action, we recommend exploring the [TypeChat example projects](https://github.com/microsoft/TypeChat/tree/main/typescript/examples). You can try them on your local machine or in a GitHub Codespace. diff --git a/typescript/examples/calendar/package.json b/typescript/examples/calendar/package.json index 881c8e34..980e18b7 100644 --- a/typescript/examples/calendar/package.json +++ b/typescript/examples/calendar/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { diff --git a/typescript/examples/coffeeShop-zod/package.json b/typescript/examples/coffeeShop-zod/package.json index 7cc06f15..fa17b18d 100644 --- a/typescript/examples/coffeeShop-zod/package.json +++ b/typescript/examples/coffeeShop-zod/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "zod": "^4.0.0" }, "devDependencies": { diff --git a/typescript/examples/coffeeShop/package.json b/typescript/examples/coffeeShop/package.json index ba9719b3..b6893261 100644 --- a/typescript/examples/coffeeShop/package.json +++ b/typescript/examples/coffeeShop/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { diff --git a/typescript/examples/crossword/package.json b/typescript/examples/crossword/package.json index 31f504c4..57ae8fc6 100644 --- a/typescript/examples/crossword/package.json +++ b/typescript/examples/crossword/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { diff --git a/typescript/examples/drawing/package.json b/typescript/examples/drawing/package.json index 1cc8d5e9..a357efaf 100644 --- a/typescript/examples/drawing/package.json +++ b/typescript/examples/drawing/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { diff --git a/typescript/examples/healthData/package.json b/typescript/examples/healthData/package.json index 57108be5..7336eaec 100644 --- a/typescript/examples/healthData/package.json +++ b/typescript/examples/healthData/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.1.3" }, "devDependencies": { diff --git a/typescript/examples/math/package.json b/typescript/examples/math/package.json index 79df155c..a0be1ea6 100644 --- a/typescript/examples/math/package.json +++ b/typescript/examples/math/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { diff --git a/typescript/examples/multiSchema/package.json b/typescript/examples/multiSchema/package.json index f5abaf4f..8ab50afe 100644 --- a/typescript/examples/multiSchema/package.json +++ b/typescript/examples/multiSchema/package.json @@ -13,7 +13,7 @@ "license": "MIT", "dependencies": { "dotenv": "^16.3.1", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "find-config": "^1.0.0", "music": "^0.0.1", "typescript": "^5.3.3" diff --git a/typescript/examples/music/package.json b/typescript/examples/music/package.json index 09036a38..f646a0f6 100644 --- a/typescript/examples/music/package.json +++ b/typescript/examples/music/package.json @@ -23,7 +23,7 @@ "find-config": "^1.0.0", "open": "^7.0.4", "sqlite3": "^6.0.1", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { diff --git a/typescript/examples/restaurant/package.json b/typescript/examples/restaurant/package.json index eebfd3a5..afcfecc0 100644 --- a/typescript/examples/restaurant/package.json +++ b/typescript/examples/restaurant/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { diff --git a/typescript/examples/sentiment-zod/package.json b/typescript/examples/sentiment-zod/package.json index 8b6bd49c..87188ff4 100644 --- a/typescript/examples/sentiment-zod/package.json +++ b/typescript/examples/sentiment-zod/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0" + "typechat": "^0.2.0" }, "devDependencies": { "@types/find-config": "1.0.4", diff --git a/typescript/examples/sentiment/package.json b/typescript/examples/sentiment/package.json index 0d07ecc8..40c2b1a4 100644 --- a/typescript/examples/sentiment/package.json +++ b/typescript/examples/sentiment/package.json @@ -13,7 +13,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { diff --git a/typescript/package-lock.json b/typescript/package-lock.json index 1657a904..ab0e9bc6 100644 --- a/typescript/package-lock.json +++ b/typescript/package-lock.json @@ -1,12 +1,12 @@ { "name": "typechat", - "version": "0.1.4", + "version": "0.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "typechat", - "version": "0.1.4", + "version": "0.2.0", "license": "MIT", "workspaces": [ "./", @@ -43,7 +43,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { @@ -82,7 +82,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { @@ -98,7 +98,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "zod": "^4.0.0" }, "devDependencies": { @@ -161,7 +161,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { @@ -199,7 +199,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { @@ -238,7 +238,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.1.3" }, "devDependencies": { @@ -276,7 +276,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { @@ -316,7 +316,7 @@ "dotenv": "^16.3.1", "find-config": "^1.0.0", "music": "^0.0.1", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { @@ -359,7 +359,7 @@ "find-config": "^1.0.0", "open": "^7.0.4", "sqlite3": "^6.0.1", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { @@ -399,7 +399,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { @@ -437,7 +437,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0", + "typechat": "^0.2.0", "typescript": "^5.3.3" }, "devDependencies": { @@ -452,7 +452,7 @@ "dependencies": { "dotenv": "^16.3.1", "find-config": "^1.0.0", - "typechat": "^0.1.0" + "typechat": "^0.2.0" }, "devDependencies": { "@types/find-config": "1.0.4", diff --git a/typescript/package.json b/typescript/package.json index f9640e3b..1df97ea9 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,7 +1,7 @@ { "name": "typechat", "author": "Microsoft", - "version": "0.1.4", + "version": "0.2.0", "license": "MIT", "description": "TypeChat is an experimental library that makes it easy to build natural language interfaces using types.", "keywords": [ @@ -20,7 +20,9 @@ "url": "https://github.com/microsoft/TypeChat/issues" }, "scripts": { - "build": "tsc -p src", + "build": "npm run build:cjs && npm run build:esm", + "build:cjs": "tsc -p src", + "build:esm": "tsc -p src/tsconfig.esm.json && node -e \"const fs = require('fs'); fs.writeFileSync('dist/esm/package.json', JSON.stringify({ type: 'module' })); fs.copyFileSync('dist/esm/schemaValidation.d.ts', 'dist/schemaValidation.d.ts'); fs.writeFileSync('dist/esm/schemaValidation.d.ts', 'export { typeChatSchemaValidation } from \\'../schemaValidation.js\\';\\n')\"", "test": "npm run build && tsc -p test && node --test \"out/**/*.test.js\" \"tests/**/*.test.mjs\"", "build-all": "npm run build && npm run build --workspaces", "prepare": "npm run build-all", @@ -29,13 +31,55 @@ "publish-package": "npm publish", "publish-package:dry-run": "npm publish --dry-run" }, + "type": "commonjs", "main": "./dist/index.js", + "module": "./dist/esm/index.mjs", "types": "./dist/index.d.ts", "exports": { - ".": "./dist/index.js", - "./ts": "./dist/ts/index.js", - "./zod": "./dist/zod/index.js", - "./interactive": "./dist/interactive/index.js" + ".": { + "import": { + "types": "./dist/esm/index.d.mts", + "default": "./dist/esm/index.mjs" + }, + "require": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + }, + "default": "./dist/index.js" + }, + "./ts": { + "import": { + "types": "./dist/esm/ts/index.d.mts", + "default": "./dist/esm/ts/index.mjs" + }, + "require": { + "types": "./dist/ts/index.d.ts", + "default": "./dist/ts/index.js" + }, + "default": "./dist/ts/index.js" + }, + "./zod": { + "import": { + "types": "./dist/esm/zod/index.d.mts", + "default": "./dist/esm/zod/index.mjs" + }, + "require": { + "types": "./dist/zod/index.d.ts", + "default": "./dist/zod/index.js" + }, + "default": "./dist/zod/index.js" + }, + "./interactive": { + "import": { + "types": "./dist/esm/interactive/index.d.mts", + "default": "./dist/esm/interactive/index.mjs" + }, + "require": { + "types": "./dist/interactive/index.d.ts", + "default": "./dist/interactive/index.js" + }, + "default": "./dist/interactive/index.js" + } }, "engines": { "node": ">=24.22.1" diff --git a/typescript/src/index.mts b/typescript/src/index.mts new file mode 100644 index 00000000..97939873 --- /dev/null +++ b/typescript/src/index.mts @@ -0,0 +1,2 @@ +export * from './index.js'; +export * as default from './index.js'; diff --git a/typescript/src/index.ts b/typescript/src/index.ts index 7029f515..08b807b4 100644 --- a/typescript/src/index.ts +++ b/typescript/src/index.ts @@ -1,3 +1,3 @@ -export * from './result'; -export * from './model'; -export * from './typechat'; +export * from './result.js'; +export * from './model.js'; +export * from './typechat.js'; diff --git a/typescript/src/interactive/index.mts b/typescript/src/interactive/index.mts new file mode 100644 index 00000000..97939873 --- /dev/null +++ b/typescript/src/interactive/index.mts @@ -0,0 +1,2 @@ +export * from './index.js'; +export * as default from './index.js'; diff --git a/typescript/src/interactive/index.ts b/typescript/src/interactive/index.ts index aad61099..68a50677 100644 --- a/typescript/src/interactive/index.ts +++ b/typescript/src/interactive/index.ts @@ -1 +1 @@ -export * from './interactive'; +export * from './interactive.js'; diff --git a/typescript/src/model.ts b/typescript/src/model.ts index e550f66d..5a2dffa0 100644 --- a/typescript/src/model.ts +++ b/typescript/src/model.ts @@ -1,4 +1,4 @@ -import { Result, success, error, withResponseMetadata, TypeChatResponseMetadata, TypeChatTokenUsage } from "./result"; +import { Result, success, error, withResponseMetadata, TypeChatResponseMetadata, TypeChatTokenUsage } from "./result.js"; /** * Represents a section of an LLM prompt with an associated role. TypeChat uses the "user" role for diff --git a/typescript/src/schemaValidation.ts b/typescript/src/schemaValidation.ts new file mode 100644 index 00000000..d00cd390 --- /dev/null +++ b/typescript/src/schemaValidation.ts @@ -0,0 +1,4 @@ +/** + * Optional capability for validators that can check schema configuration without an instance. + */ +export const typeChatSchemaValidation: unique symbol = Symbol.for("typechat.schemaValidation"); diff --git a/typescript/src/ts/index.mts b/typescript/src/ts/index.mts new file mode 100644 index 00000000..97939873 --- /dev/null +++ b/typescript/src/ts/index.mts @@ -0,0 +1,2 @@ +export * from './index.js'; +export * as default from './index.js'; diff --git a/typescript/src/ts/index.ts b/typescript/src/ts/index.ts index ef6f6876..7117aa35 100644 --- a/typescript/src/ts/index.ts +++ b/typescript/src/ts/index.ts @@ -1,2 +1,2 @@ -export * from './validate'; -export * from './program'; +export * from './validate.js'; +export * from './program.js'; diff --git a/typescript/src/ts/program.ts b/typescript/src/ts/program.ts index 56ee091c..b771c653 100644 --- a/typescript/src/ts/program.ts +++ b/typescript/src/ts/program.ts @@ -1,7 +1,7 @@ -import { Result, error, success } from "../result"; -import { TypeChatLanguageModel } from "../model"; -import { createTypeScriptJsonValidator } from "./validate"; -import { TypeChatJsonTranslator, createJsonTranslator } from "../typechat"; +import { Result, error, success } from "../result.js"; +import { TypeChatLanguageModel } from "../model.js"; +import { createTypeScriptJsonValidator } from "./validate.js"; +import { TypeChatJsonTranslator, createJsonTranslator } from "../typechat.js"; const programSchemaText = `// A program consists of a sequence of function calls that are evaluated in order. export type Program = { diff --git a/typescript/src/ts/validate.ts b/typescript/src/ts/validate.ts index 4da54299..550d6158 100644 --- a/typescript/src/ts/validate.ts +++ b/typescript/src/ts/validate.ts @@ -1,23 +1,10 @@ -import { createRequire } from 'node:module'; -import { Result, success, error } from '../result'; -import { typeChatSchemaValidation, type TypeChatJsonValidator } from "../typechat"; - -// TypeScript 7 ships as an ES module, while this package is emitted as CommonJS. Node's -// `require(esm)` support (Node >=22.12) lets us load it synchronously, and `resolution-mode` -// makes the TypeScript compiler resolve the ESM-only types from a CommonJS file. // TODO: Revisit these `typescript/unstable/*` imports once a stable API is available. -type SyncModule = typeof import('typescript/unstable/sync', { with: { 'resolution-mode': 'import' } }); -type FileSystemModule = typeof import('typescript/unstable/fs', { with: { 'resolution-mode': 'import' } }); -type AstIsModule = typeof import('typescript/unstable/ast/is', { with: { 'resolution-mode': 'import' } }); - -type Checker = InstanceType; -type Diagnostic = import('typescript/unstable/sync', { with: { 'resolution-mode': 'import' } }).Diagnostic; -type SourceFile = import('typescript/unstable/ast', { with: { 'resolution-mode': 'import' } }).SourceFile; - -const requireEsm = createRequire(__filename); -const { API, NodeBuilderFlags, SymbolFlags }: SyncModule = requireEsm('typescript/unstable/sync'); -const { createVirtualFileSystem }: FileSystemModule = requireEsm('typescript/unstable/fs'); -const { isTypeReferenceNode, isVariableStatement }: AstIsModule = requireEsm('typescript/unstable/ast/is'); +import { API, NodeBuilderFlags, SymbolFlags, type Checker, type Diagnostic } from 'typescript/unstable/sync'; +import { createVirtualFileSystem } from 'typescript/unstable/fs'; +import type { SourceFile } from 'typescript/unstable/ast'; +import { isTypeReferenceNode, isVariableStatement } from 'typescript/unstable/ast/is'; +import { Result, success, error } from '../result.js'; +import { typeChatSchemaValidation, type TypeChatJsonValidator } from "../typechat.js"; const libText = `interface Array { length: number, [n: number]: T } interface Object { toString(): string } diff --git a/typescript/src/tsconfig.esm.json b/typescript/src/tsconfig.esm.json new file mode 100644 index 00000000..0ca2357a --- /dev/null +++ b/typescript/src/tsconfig.esm.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "module": "es2022", + "moduleResolution": "bundler", + "outDir": "../dist/esm" + }, + "include": ["./**/*.ts", "./**/*.mts"] +} diff --git a/typescript/src/tsconfig.json b/typescript/src/tsconfig.json index 9e97b242..9f5a767b 100644 --- a/typescript/src/tsconfig.json +++ b/typescript/src/tsconfig.json @@ -2,7 +2,7 @@ "compilerOptions": { "target": "es2021", "lib": ["es2021"], - "module": "node16", + "module": "node20", "types": ["node"], "esModuleInterop": true, "outDir": "../dist", @@ -10,5 +10,6 @@ "strict": true, "exactOptionalPropertyTypes": true, "declaration": true - } + }, + "include": ["./**/*.ts"] } diff --git a/typescript/src/typechat.ts b/typescript/src/typechat.ts index ef1077dc..66b082f1 100644 --- a/typescript/src/typechat.ts +++ b/typescript/src/typechat.ts @@ -1,5 +1,8 @@ -import { Result, success, error, withResponseMetadata, TypeChatResponseMetadata, Error as TypeChatError } from "./result"; -import { TypeChatLanguageModel, PromptSection, PromptContent } from "./model"; +import { Result, success, error, withResponseMetadata, TypeChatResponseMetadata, Error as TypeChatError } from "./result.js"; +import { TypeChatLanguageModel, PromptSection, PromptContent } from "./model.js"; +import { typeChatSchemaValidation } from "./schemaValidation.js"; + +export { typeChatSchemaValidation } from "./schemaValidation.js"; /** * Represents an object that can translate natural language requests in JSON objects of the given type. @@ -88,11 +91,6 @@ export interface TypeChatJsonValidator { validate(jsonObject: object): Result; } -/** - * Optional capability for validators that can check schema configuration without an instance. - */ -export const typeChatSchemaValidation: unique symbol = Symbol("TypeChat schema validation"); - export interface TypeChatJsonValidatorWithSchemaValidation extends TypeChatJsonValidator { [typeChatSchemaValidation](): Result; } diff --git a/typescript/src/zod/index.mts b/typescript/src/zod/index.mts new file mode 100644 index 00000000..97939873 --- /dev/null +++ b/typescript/src/zod/index.mts @@ -0,0 +1,2 @@ +export * from './index.js'; +export * as default from './index.js'; diff --git a/typescript/src/zod/index.ts b/typescript/src/zod/index.ts index 63a2929c..d5593bf2 100644 --- a/typescript/src/zod/index.ts +++ b/typescript/src/zod/index.ts @@ -1 +1 @@ -export * from './validate'; +export * from './validate.js'; diff --git a/typescript/src/zod/validate.ts b/typescript/src/zod/validate.ts index 9af038b0..fff47237 100644 --- a/typescript/src/zod/validate.ts +++ b/typescript/src/zod/validate.ts @@ -1,6 +1,6 @@ import { z } from "zod"; -import { success, error } from '../result'; -import { TypeChatJsonValidator } from '../typechat'; +import { success, error } from '../result.js'; +import { TypeChatJsonValidator } from '../typechat.js'; /** * Returns a JSON validator for a given Zod schema. The schema is supplied as an object where each property provides diff --git a/typescript/tests/package.test.mjs b/typescript/tests/package.test.mjs index 6a7a5e0a..d724841a 100644 --- a/typescript/tests/package.test.mjs +++ b/typescript/tests/package.test.mjs @@ -1,22 +1,390 @@ import assert from "node:assert/strict"; -import { execFileSync } from "node:child_process"; -import { - cpSync, - existsSync, - mkdirSync, - mkdtempSync, - readFileSync, - readdirSync, - rmSync, - symlinkSync, - writeFileSync, -} from "node:fs"; -import os from "node:os"; +import { execFileSync, spawnSync } from "node:child_process"; +import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { createRequire } from "node:module"; +import os, { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { after, before, describe, test } from "node:test"; +import { fileURLToPath, pathToFileURL } from "node:url"; import path from "node:path"; -import { fileURLToPath } from "node:url"; -import test from "node:test"; -const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const require = createRequire(import.meta.url); +const packageRoot = fileURLToPath(new URL("..", import.meta.url)); +const directory = realpathSync(mkdtempSync(join(tmpdir(), "typechat-package-"))); +const withPeers = join(directory, "with-peers"); +const withoutPeers = join(directory, "without-peers"); +const stagedPackage = join(withPeers, "node_modules", "typechat"); +const entryPoints = [ + ["typechat", "index"], + ["typechat/ts", "ts/index"], + ["typechat/zod", "zod/index"], + ["typechat/interactive", "interactive/index"], +]; +const childEnv = { ...process.env, NODE_OPTIONS: "", VSCODE_INSPECTOR_OPTIONS: "", NODE_PATH: "" }; +let packedFiles; + +before(() => { + const options = { cwd: packageRoot, encoding: "utf8", env: childEnv, timeout: 30000 }; + const packed = process.platform === "win32" + ? spawnSync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", "npm pack --ignore-scripts --dry-run --json"], options) + : spawnSync("npm", ["pack", "--ignore-scripts", "--dry-run", "--json"], options); + assert.ifError(packed.error); + assert.equal(packed.status, 0, `${packed.stdout}${packed.stderr}`); + packedFiles = JSON.parse(packed.stdout)[0].files.map(file => file.path); + + for (const consumer of [withPeers, withoutPeers]) { + for (const file of packedFiles) { + const destination = join(consumer, "node_modules", "typechat", file); + mkdirSync(dirname(destination), { recursive: true }); + copyFileSync(join(packageRoot, file), destination); + } + } + for (const peer of ["typescript", "zod"]) { + symlinkSync( + dirname(require.resolve(`${peer}/package.json`)), + join(withPeers, "node_modules", peer), + process.platform === "win32" ? "junction" : "dir" + ); + } + writeFileSync(join(withPeers, "requests.txt"), "first\n\nsecond\r\n"); +}); + +after(() => { + rmSync(directory, { recursive: true, force: true }); +}); + +function runConsumer(consumer, fileName, source) { + const file = join(consumer, fileName); + writeFileSync(file, source); + const result = spawnSync(process.execPath, [file], { + cwd: consumer, + encoding: "utf8", + env: childEnv, + timeout: 30000, + }); + assert.ifError(result.error); + assert.equal(result.status, 0, `${result.stdout}${result.stderr}`); +} + +describe("published package", () => { + test("includes both builds and their declarations for every entry point", () => { + for (const [, entry] of entryPoints) { + for (const [prefix, extensions] of [ + ["dist", [".js", ".d.ts"]], + ["dist/esm", [".mjs", ".d.mts"]], + ]) { + for (const extension of extensions) { + assert.ok(packedFiles.includes(`${prefix}/${entry}${extension}`)); + } + } + } + assert.ok(packedFiles.includes("dist/esm/package.json")); + assert.equal(JSON.parse(readFileSync(join(stagedPackage, "dist", "esm", "package.json"), "utf8")).type, "module"); + assert.ok(!packedFiles.some(file => file.startsWith("src/") || file.startsWith("tests/"))); + }); + + test("selects native ESM and CommonJS builds with identical named exports", () => { + const expected = entryPoints.map(([specifier, entry]) => ({ + specifier, + cjs: join(stagedPackage, "dist", `${entry}.js`), + esm: pathToFileURL(join(stagedPackage, "dist", "esm", `${entry}.mjs`)).href, + })); + runConsumer(withPeers, "exports.mjs", ` + import assert from "node:assert/strict"; + import { createRequire } from "node:module"; + const require = createRequire(import.meta.url); + for (const { specifier, cjs, esm } of ${JSON.stringify(expected)}) { + assert.equal(require.resolve(specifier), cjs); + assert.equal(import.meta.resolve(specifier), esm); + const commonjs = require(specifier); + const native = await import(specifier); + const { default: defaultExport, ...namedExports } = native; + assert.equal("default" in commonjs, false); + assert.deepEqual(Object.keys(namedExports).sort(), Object.keys(commonjs).sort()); + assert.deepEqual(Object.keys(defaultExport).sort(), Object.keys(commonjs).sort()); + for (const name of Object.keys(commonjs)) { + assert.equal(defaultExport[name], native[name]); + } + } + `); + }); + + test("resolves package entry points through a symlinked temporary directory", () => { + const target = join(directory, "tmp"); + const link = join(directory, "tmp-link"); + mkdirSync(target); + symlinkSync(target, link, directoryLinkType); + const env = { ...childEnv, TMPDIR: link, TEMP: link, TMP: link }; + // The nested runner needs its own reporting context. + delete env.NODE_TEST_CONTEXT; + const result = spawnSync(process.execPath, [ + "--test", + "--test-reporter=tap", + "--test-name-pattern=selects native ESM and CommonJS builds with identical named exports", + fileURLToPath(import.meta.url), + ], { + cwd: packageRoot, + encoding: "utf8", + env, + timeout: 30000, + }); + assert.ifError(result.error); + assert.equal(result.status, 0, `${result.stdout}${result.stderr}`); + assert.match(result.stdout, /^# pass 1$/m); + }); + + test("preserves native ESM default imports for every entry point", () => { + runConsumer(withPeers, "default-imports.mjs", ` + import assert from "node:assert/strict"; + import core, { success } from "typechat"; + import ts, { createTypeScriptJsonValidator } from "typechat/ts"; + import adapter, { createZodJsonValidator } from "typechat/zod"; + import interactive, { processRequests } from "typechat/interactive"; + assert.equal(core.success, success); + assert.equal(ts.createTypeScriptJsonValidator, createTypeScriptJsonValidator); + assert.equal(adapter.createZodJsonValidator, createZodJsonValidator); + assert.equal(interactive.processRequests, processRequests); + assert.deepEqual(core.success("ok"), { success: true, data: "ok" }); + `); + }); + + for (const format of ["cjs", "esm"]) { + test(`${format} core and interactive entry points load without optional peers`, () => { + const imports = format === "esm" + ? `import core, { success, getData } from "typechat"; + import interactive, { processRequests } from "typechat/interactive";` + : `const core = require("typechat"); + const interactive = require("typechat/interactive"); + const { success, getData } = core; + const { processRequests } = interactive;`; + runConsumer(withoutPeers, `core.${format === "esm" ? "mjs" : "cjs"}`, ` + ${imports} + ${format === "esm" ? 'import assert from "node:assert/strict";' : 'const assert = require("node:assert/strict");'} + assert.equal(core.success, success); + assert.equal(interactive.processRequests, processRequests); + assert.deepEqual(success("ok"), { success: true, data: "ok" }); + assert.equal(getData(success("ok")), "ok"); + assert.equal(typeof processRequests, "function"); + `); + }); + + test(`${format} supports translation, both validators, programs, and interactive input`, () => { + const imports = format === "esm" + ? `import assert from "node:assert/strict"; + import * as core from "typechat"; + import * as ts from "typechat/ts"; + import * as adapter from "typechat/zod"; + import * as interactive from "typechat/interactive"; + import { z } from "zod";` + : `const assert = require("node:assert/strict"); + const core = require("typechat"); + const ts = require("typechat/ts"); + const adapter = require("typechat/zod"); + const interactive = require("typechat/interactive"); + const { z } = require("zod");`; + runConsumer(withPeers, `behavior.${format === "esm" ? "mjs" : "cjs"}`, ` + ${imports} + (async () => { + const value = { value: "ok" }; + const validator = ts.createTypeScriptJsonValidator( + "export interface Value { value: string; }", "Value" + ); + try { + assert.deepEqual(validator.validate(value), core.success(value)); + assert.equal(validator.validate({ value: 1 }).success, false); + const model = { complete: async () => core.success(JSON.stringify(value)) }; + const translator = core.createJsonTranslator(model, validator); + assert.deepEqual(await translator.translate("test"), core.success(value)); + } finally { + validator.close(); + } + const schema = { Value: z.object({ value: z.string() }) }; + const zodValidator = adapter.createZodJsonValidator(schema, "Value"); + assert.deepEqual(zodValidator.validate(value), core.success(value)); + assert.equal(zodValidator.validate({ value: 1 }).success, false); + assert.match(adapter.getZodSchemaAsTypeScript(schema), /interface Value/); + const calls = []; + await ts.evaluateJsonProgram( + { "@steps": [{ "@func": "echo", "@args": ["ok"] }] }, + async (name, args) => { calls.push({ name, args }); return args[0]; } + ); + assert.deepEqual(calls, [{ name: "echo", args: ["ok"] }]); + const requests = []; + await interactive.processRequests("> ", "requests.txt", async request => { requests.push(request); }); + assert.deepEqual(requests, ["first", "second"]); + })().catch(error => { console.error(error); process.exitCode = 1; }); + `); + }); + + test(`${format} translators preflight validators from the other module format`, () => { + runConsumer(withPeers, `mixed-${format}.mjs`, ` + import assert from "node:assert/strict"; + import { createRequire } from "node:module"; + const require = createRequire(import.meta.url); + const core = ${format === "esm" ? 'await import("typechat")' : 'require("typechat")'}; + const { createTypeScriptJsonValidator } = ${format === "esm" ? 'require("typechat/ts")' : 'await import("typechat/ts")'}; + let modelCalls = 0; + const model = { + complete: async () => { + modelCalls++; + return core.success(JSON.stringify({ value: modelCalls === 1 ? 1 : "ok" })); + } + }; + const invalidValidator = createTypeScriptJsonValidator( + "export interface Value { value: MissingType; }", "Value" + ); + try { + const translator = core.createJsonTranslator(model, invalidValidator); + const result = await translator.translate("test"); + assert.equal(result.success, false); + assert.equal(modelCalls, 0); + assert.match(result.message, /^Schema validation failed before model request:/); + assert.match(result.message, /Cannot find name 'MissingType'/); + } finally { + invalidValidator.close(); + } + const validValidator = createTypeScriptJsonValidator( + "export interface Value { value: string; }", "Value" + ); + try { + const translator = core.createJsonTranslator(model, validValidator); + assert.deepEqual(await translator.translate("test"), core.success({ value: "ok" })); + assert.equal(modelCalls, 2); + } finally { + validValidator.close(); + } + `); + }); + } + + for (const module of ["node16", "nodenext"]) { + test(`resolves format-specific declarations using ${module}`, () => { + const source = ` + import { + createJsonTranslator, success, typeChatSchemaValidation, type Result, type Success, + type TypeChatLanguageModel, type TypeChatJsonTranslator, + type TypeChatJsonValidatorWithSchemaValidation + } from "typechat"; + import { + createTypeScriptJsonValidator, evaluateJsonProgram, + type TypeScriptJsonValidator, type TypeScriptJsonValidatorWithSchemaValidation, type Program + } from "typechat/ts"; + import { createZodJsonValidator } from "typechat/zod"; + import { processRequests } from "typechat/interactive"; + import { z } from "zod"; + interface Value { value: string; } + const model: TypeChatLanguageModel = { complete: async () => success('{"value":"ok"}') }; + const validator: TypeScriptJsonValidator = createTypeScriptJsonValidator( + "export interface Value { value: string; }", "Value" + ); + const translator: TypeChatJsonTranslator = createJsonTranslator(model, validator); + const result: Result = createZodJsonValidator( + { Value: z.object({ value: z.string() }) }, "Value" + ).validate({ value: "ok" }); + const program: Program = { "@steps": [] }; + evaluateJsonProgram(program, async () => "ok"); + processRequests("> ", undefined, async request => { const text: string = request; }); + // @ts-expect-error The result must preserve its data type. + const invalid: Success = success("ok"); + // @ts-expect-error Request callbacks must return a promise. + processRequests("> ", undefined, () => 1); + `; + const defaultImportSource = ` + import core from "typechat"; + import ts from "typechat/ts"; + import adapter from "typechat/zod"; + import interactive from "typechat/interactive"; + const defaultValidator: ts.TypeScriptJsonValidator = ts.createTypeScriptJsonValidator( + validator.getSchemaText(), validator.getTypeName() + ); + const defaultTranslator: core.TypeChatJsonTranslator = core.createJsonTranslator(model, defaultValidator); + const defaultResult: core.Result = adapter.createZodJsonValidator( + { Value: z.object({ value: z.string() }) }, "Value" + ).validate({ value: "ok" }); + const defaultProgram: ts.Program = program; + ts.evaluateJsonProgram(defaultProgram, async () => "ok"); + interactive.processRequests("> ", undefined, async request => { const text: string = request; }); + // @ts-expect-error Default imports must preserve their result types. + const invalidDefault: core.Success = core.success("ok"); + // @ts-expect-error Default imports must preserve callback types. + interactive.processRequests("> ", undefined, () => 1); + `; + const capabilitySource = ` + import type { TypeChatJsonValidatorWithSchemaValidation } from "typechat"; + import { createTypeScriptJsonValidator } from "typechat/ts"; + export { typeChatSchemaValidation } from "typechat"; + export const validator = createTypeScriptJsonValidator<{ value: string }>( + "export interface Value { value: string; }", "Value" + ); + export const capability: TypeChatJsonValidatorWithSchemaValidation<{ value: string }> = validator; + `; + const mixedSource = ` + const sharedSymbol: typeof typeChatSchemaValidation = other.typeChatSchemaValidation; + const mixedValidator: TypeScriptJsonValidatorWithSchemaValidation = other.validator; + const mixedCapability: TypeChatJsonValidatorWithSchemaValidation = other.capability; + const validatorResult: Result = other.validator[typeChatSchemaValidation](); + const capabilityResult: Result = other.capability[typeChatSchemaValidation](); + // @ts-expect-error Mixed-format capabilities must preserve their instance type. + const invalidCapability: TypeChatJsonValidatorWithSchemaValidation<{ value: number }> = other.capability; + // @ts-expect-error Schema validation does not return a validated instance. + const invalidResult: Result = other.validator[typeChatSchemaValidation](); + const unrelatedSymbol = Symbol("unrelated"); + // @ts-expect-error Only the capability symbol identifies schema validation. + other.validator[unrelatedSymbol](); + `; + for (const extension of ["cts", "mts"]) { + writeFileSync(join(withPeers, `capability.${extension}`), capabilitySource); + const mixedFormatSource = extension === "mts" + ? ` + import * as other from "./capability.cjs"; + ${mixedSource} + ` + : ` + async function checkEsmCapability() { + const other = await import("./capability.mjs"); + ${mixedSource} + } + `; + writeFileSync( + join(withPeers, `consumer.${extension}`), + source + (extension === "mts" ? defaultImportSource : "") + mixedFormatSource + ); + } + writeFileSync(join(withPeers, "tsconfig.json"), JSON.stringify({ + compilerOptions: { + target: "es2021", + lib: ["es2021", "dom"], + module, + moduleResolution: module, + strict: true, + noEmit: true, + types: [], + }, + files: ["consumer.cts", "consumer.mts"], + })); + const compiler = join(dirname(require.resolve("typescript/package.json")), "bin", "tsc"); + const result = spawnSync(process.execPath, [compiler, "-p", withPeers, "--traceResolution", "--pretty", "false"], { + encoding: "utf8", + env: childEnv, + timeout: 30000, + }); + assert.ifError(result.error); + const diagnostics = result.stdout.split(/\r?\n/).filter(line => line.includes("error TS")).join("\n"); + assert.equal(result.status, 0, `${diagnostics}\n${result.stderr}`); + const trace = result.stdout.replaceAll("\\", "/"); + for (const [specifier, entry] of entryPoints) { + for (const [prefix, extension] of [["dist", ".d.ts"], ["dist/esm", ".d.mts"]]) { + const declaration = join(stagedPackage, prefix, `${entry}${extension}`).replaceAll("\\", "/"); + assert.ok( + trace.includes(`Module name '${specifier}' was successfully resolved to '${declaration}'`), + `${specifier} must resolve ${declaration}` + ); + } + } + }); + } +}); + const npmCli = process.env.npm_execpath ?? path.resolve( path.dirname(process.execPath), process.platform === "win32" ? "node_modules/npm/bin/npm-cli.js" : "../lib/node_modules/npm/bin/npm-cli.js"