diff --git a/.changeset/26208-node10-resolution-unsupported.md b/.changeset/26208-node10-resolution-unsupported.md new file mode 100644 index 00000000000..0d65f3e527a --- /dev/null +++ b/.changeset/26208-node10-resolution-unsupported.md @@ -0,0 +1,26 @@ +--- +'@objectstack/spec': patch +'@objectstack/cli': patch +'@objectstack/connector-imap': patch +'@objectstack/core': patch +'create-objectstack': patch +'@objectstack/lint': patch +'@objectstack/metadata': patch +'@objectstack/metadata-core': patch +'@objectstack/objectql': patch +'@objectstack/platform-objects': patch +'@objectstack/plugin-auth': patch +'@objectstack/plugin-webhooks': patch +'@objectstack/service-cluster': patch +'@objectstack/service-datasource': patch +'@objectstack/types': patch +--- + +docs: TypeScript's legacy `node10` module resolution is unsupported for packages with subpath exports + +Clause-②: no +Metadata-protocol: none + +These fifteen packages declare their entry points only through `exports`, including subpaths such as `@objectstack/spec/kernel`. TypeScript's legacy `node10` resolution (`moduleResolution: "node"`, the default when `module` is `commonjs`) ignores `exports`, so a project configured that way cannot resolve the types of any subpath import, while the root entry still appears to work. Each package's README now says so in one line, and the plugin development guide gains a "Module resolution" paragraph. No `exports` map changes and no `typesVersions` fallback is added. + +What to do: set `moduleResolution` to `node16`, `nodenext` or `bundler` in the consuming project's `tsconfig.json`. diff --git a/content/docs/plugins/development.mdx b/content/docs/plugins/development.mdx index 7a973f0a798..9b0a8247a88 100644 --- a/content/docs/plugins/development.mdx +++ b/content/docs/plugins/development.mdx @@ -53,6 +53,10 @@ Create `tsconfig.json`: } ``` +### Module resolution + +The published `@objectstack/*` packages declare their entry points only through `exports`, including subpaths such as `@objectstack/spec/kernel`. Set `moduleResolution` to `bundler` (as above), `node16` or `nodenext`. TypeScript's legacy `node10` resolution (spelled `"node"`, and the default when `module` is `commonjs`) is not supported: it ignores `exports`, so every subpath import fails to resolve its types while the root entry still appears to work. The packages ship no `typesVersions` fallback for it. + --- ## Step 2: Define the Package Manifest diff --git a/packages/cli/README.md b/packages/cli/README.md index 5bcd7bbd15f..5f2985c0739 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -4,6 +4,8 @@ Command Line Interface for building metadata-driven applications with the Object Built on [oclif](https://oclif.io/) — commands are auto-discovered, and plugins can extend the CLI without modifying the main package. +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Installation ```bash diff --git a/packages/connectors/connector-imap/README.md b/packages/connectors/connector-imap/README.md index a15d58d58d8..5d78680ab16 100644 --- a/packages/connectors/connector-imap/README.md +++ b/packages/connectors/connector-imap/README.md @@ -4,6 +4,8 @@ The IMAP connector of ObjectStack's inbound mail: a **read-only IMAP4rev1 sessio It registers no `connector_action` handlers and ships no plugin: nothing in a flow calls IMAP; the mailbox service does. +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## What it provides - **`openImapSession({ account, credentials, timeoutMs?, maxLiteralBytes?, maxCommandBytes? })`** — connects, reads the greeting, learns the server's capabilities, resolves the credential and authenticates. The session it answers: diff --git a/packages/core/README.md b/packages/core/README.md index 2490e0b165e..f677f6bfbef 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -5,6 +5,8 @@ [![npm](https://img.shields.io/npm/v/@objectstack/core.svg)](https://www.npmjs.com/package/@objectstack/core) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](../../LICENSING.md) +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Overview `@objectstack/core` is the foundation every ObjectStack runtime is built on. It hosts two kernels, a plugin lifecycle, a typed service registry, a structured logger, and a plugin-to-plugin event bus: diff --git a/packages/create-objectstack/README.md b/packages/create-objectstack/README.md index 61aa29d20a7..6e116da4e57 100644 --- a/packages/create-objectstack/README.md +++ b/packages/create-objectstack/README.md @@ -6,6 +6,8 @@ Scaffold a new [ObjectStack](https://objectstack.ai) project in seconds. npm create objectstack@latest my-app ``` +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Usage ```bash diff --git a/packages/lint/README.md b/packages/lint/README.md index a7a85b0a760..1f233c5af6a 100644 --- a/packages/lint/README.md +++ b/packages/lint/README.md @@ -11,6 +11,8 @@ generated metadata to the same bar as hand-authored metadata. Dependency direction is one-way — `lint` → `@objectstack/spec` (the contract). It never depends on a runtime and is never bundled into a frontend. +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## API - `validateWidgetBindings(stack)` — dashboard widget → dataset → measure/dimension diff --git a/packages/metadata-core/README.md b/packages/metadata-core/README.md index d35595a036d..d32609f13d5 100644 --- a/packages/metadata-core/README.md +++ b/packages/metadata-core/README.md @@ -12,6 +12,8 @@ access, no database driver. Implementations live in: - `@objectstack/metadata` (`FileSystemRepository`, `LayeredRepository`) - `@objectstack/metadata-postgres` (M1+) +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Exports ```typescript diff --git a/packages/metadata/README.md b/packages/metadata/README.md index cea787853e3..5d728666afc 100644 --- a/packages/metadata/README.md +++ b/packages/metadata/README.md @@ -6,6 +6,8 @@ It implements the **`IMetadataService`** contract from `@objectstack/spec` and acts as the single source of truth that all other packages depend on. +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Architecture Overview ``` diff --git a/packages/objectql/README.md b/packages/objectql/README.md index c2e2b58e745..24dd1e8f298 100644 --- a/packages/objectql/README.md +++ b/packages/objectql/README.md @@ -2,6 +2,8 @@ The **Data Engine** for ObjectStack. It acts as a semantic layer between your application code and the underlying database. +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Features - **Universal API**: A consistent query interface (`find`, `insert`, `update`, `delete`) regardless of the storage backend. diff --git a/packages/platform-objects/README.md b/packages/platform-objects/README.md index 229f45213cf..80c70746ec9 100644 --- a/packages/platform-objects/README.md +++ b/packages/platform-objects/README.md @@ -7,3 +7,5 @@ import { PlatformObjectsPlugin } from '@objectstack/platform-objects'; ``` Documentation: [Packages](https://objectstack.ai/docs/plugins/packages) + +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). diff --git a/packages/plugins/plugin-auth/README.md b/packages/plugins/plugin-auth/README.md index 178e18a4aee..608913190f6 100644 --- a/packages/plugins/plugin-auth/README.md +++ b/packages/plugins/plugin-auth/README.md @@ -4,6 +4,8 @@ Authentication & Identity Plugin for ObjectStack. > **✨ Status:** ObjectQL-based authentication implementation! Uses ObjectQL for data persistence (no third-party ORM required). Core authentication structure is in place with better-auth v1.4.18. +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Features ### Currently Implemented diff --git a/packages/plugins/plugin-webhooks/README.md b/packages/plugins/plugin-webhooks/README.md index d5d282883ed..42baf1da009 100644 --- a/packages/plugins/plugin-webhooks/README.md +++ b/packages/plugins/plugin-webhooks/README.md @@ -7,3 +7,5 @@ import { WebhookOutboxPlugin } from '@objectstack/plugin-webhooks'; ``` Documentation: [Webhooks](https://objectstack.ai/docs/automation/webhooks) + +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). diff --git a/packages/services/service-cluster/README.md b/packages/services/service-cluster/README.md index 7727585e1aa..9ff0262c686 100644 --- a/packages/services/service-cluster/README.md +++ b/packages/services/service-cluster/README.md @@ -9,3 +9,5 @@ import { ClusterServicePlugin } from '@objectstack/service-cluster'; Documentation: [Cluster](https://objectstack.ai/docs/kernel/cluster) `@objectstack/service-cluster/testing` (the pub/sub, lock, KV and counter contract suites) is **ESM-only**: it imports `vitest`, whose own `require()` entry throws, so the subpath declares only an `import` condition. Load it with `import`; `require()` is refused with `ERR_PACKAGE_PATH_NOT_EXPORTED`. + +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). diff --git a/packages/services/service-datasource/README.md b/packages/services/service-datasource/README.md index aa739de2e61..f30bcd568a4 100644 --- a/packages/services/service-datasource/README.md +++ b/packages/services/service-datasource/README.md @@ -14,6 +14,8 @@ because the runtime admin was once private; now that both are open-source, they are one package. The two plugins still mount independently — merging the package did not couple them.) +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Open-source mechanism, injectable tier line This package is mechanism only. Credential storage is delegated to a diff --git a/packages/spec/README.md b/packages/spec/README.md index 7587b7de533..fd5bc5f7742 100644 --- a/packages/spec/README.md +++ b/packages/spec/README.md @@ -4,6 +4,8 @@ The **Source of Truth** for the ObjectStack Protocol. Contains strictly typed Zod schemas that define every aspect of the system. +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Protocols - **System**: Manifests, Datasources, APIs. diff --git a/packages/types/README.md b/packages/types/README.md index c0bc9ac491c..910e76f3864 100644 --- a/packages/types/README.md +++ b/packages/types/README.md @@ -237,6 +237,8 @@ This package is designed to work with TypeScript 5.0+: } ``` +**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution). + ## Best Practices ### 1. Use Type-Only Imports