@danqiusheng/nest-nacos 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.2.0 (unreleased)
+
+- Add shared top-level `serverAddr`, `namespace`, `username`, `password`, and
+  `ssl` options so Naming and Config no longer require duplicate connection
+  settings.
+- Add `NacosModule.forRoot('host:8848')` as the smallest setup form.
+- Expand the Chinese and English usage documentation.
+
+## 1.1.0
+
+- Fix asynchronous server status and health checks.
+- Fix duplicate Config callbacks and SDK listener identity during unsubscribe.
+- Fix Naming unsubscribe-all behavior.
+- Close both SDK clients during module shutdown.
+- Fix `forRootAsync({ useClass })` and export raw client tokens.
+- Normalize the public Config namespace to the empty namespace ID.
+- Add JSON, YAML, Properties and TXT parsing, preload merge, hot-update state,
+  local fallback cache, startup failure modes and retries.
+- Add random, round-robin and weighted discovery with metadata filtering.
+- Remove false Nacos 3.x and gRPC compatibility claims.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 丹丘生
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 丹丘生
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,197 @@
+# @danqiusheng/nest-nacos
+
+Nacos 2.x configuration and service-discovery integration for NestJS 10/11.
+
+## Install
+
+```bash
+npm install @danqiusheng/nest-nacos nacos
+```
+
+## Minimal setup
+
+One address enables both Naming and Config clients:
+
+```ts
+NacosModule.forRoot('127.0.0.1:8848');
+```
+
+Authentication and a custom namespace are still configured once:
+
+```ts
+NacosModule.forRoot({
+  serverAddr: '127.0.0.1:8848',
+  namespace: 'production',
+  username: process.env.NACOS_USERNAME,
+  password: process.env.NACOS_PASSWORD,
+});
+```
+
+The public namespace and `DEFAULT_GROUP` are used by default. `serverAddr`
+also accepts an array of server addresses.
+
+## Async setup
+
+```ts
+NacosModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    serverAddr: config.getOrThrow<string>('NACOS_SERVER_ADDR'),
+    namespace: config.get<string>('NACOS_NAMESPACE') ?? 'public',
+    username: config.get<string>('NACOS_USERNAME'),
+    password: config.get<string>('NACOS_PASSWORD'),
+  }),
+});
+```
+
+`useFactory`, `useClass`, and `useExisting` are supported.
+
+## Automatic registration
+
+```ts
+NacosModule.forRoot({
+  serverAddr: '127.0.0.1:8848',
+  instances: [
+    {
+      serviceName: 'orders',
+      ip: '10.0.0.5',
+      port: 3000,
+      metadata: { environment: 'production' },
+    },
+  ],
+});
+```
+
+Plugin-managed instances are deregistered when the Nest module is destroyed.
+
+## Service discovery
+
+```ts
+constructor(
+  @InjectNacosNaming()
+  private readonly naming: NacosNamingService,
+) {}
+
+const instance = await this.naming.selectInstance('payments', {
+  strategy: 'roundRobin', // random | roundRobin | weighted
+  metadata: { environment: 'production' },
+});
+```
+
+Manual registration and subscriptions are also available:
+
+```ts
+await this.naming.register(instanceOptions);
+await this.naming.deregister(instanceOptions);
+
+this.naming.subscribe('payments', listener);
+this.naming.unSubscribe('payments', listener);
+```
+
+## Configuration center
+
+```ts
+constructor(
+  @InjectNacosConfig()
+  private readonly nacos: NacosConfigService,
+) {}
+
+const raw = await this.nacos.getConfig('application.yaml');
+const parsed = await this.nacos.getParsedConfig<AppConfig>(
+  'application.yaml',
+);
+
+this.nacos.subscribe(
+  'application.yaml',
+  'DEFAULT_GROUP',
+  (content, value) => console.log(value),
+);
+```
+
+JSON, YAML, Properties, and text are supported. Each `dataId + group` uses one
+underlying SDK subscription, regardless of the number of business listeners.
+
+Publish and remove configuration with:
+
+```ts
+await this.nacos.publish('application.json', 'DEFAULT_GROUP', content);
+await this.nacos.remove('application.json', 'DEFAULT_GROUP');
+```
+
+## Preload and fallback cache
+
+```ts
+NacosModule.forRoot({
+  serverAddr: '127.0.0.1:8848',
+  subscribeConfigs: [
+    { dataId: 'application.yaml', format: 'yaml' },
+    { dataId: 'database.properties', format: 'properties' },
+  ],
+  configLoading: {
+    failureMode: 'fallback', // throw | fallback | continue
+    cacheDir: '.nacos-cache',
+    retry: { attempts: 3, delayMs: 300 },
+  },
+});
+
+const merged = await this.nacos.getMergedConfig<AppConfig>();
+```
+
+Successful remote loads update cache files atomically. In `fallback` mode the
+cache is used when Nacos is unavailable.
+
+## Advanced client-specific options
+
+Nested options are only needed when Naming and Config use different settings:
+
+```ts
+NacosModule.forRoot({
+  naming: {
+    serverList: 'naming.example:8848',
+    namespace: 'services',
+  },
+  config: {
+    serverAddr: 'config.example:8848',
+    namespace: 'configuration',
+  },
+});
+```
+
+Nested fields override shared top-level fields. Supplying only `naming` or
+only `config` enables only that client.
+
+## Health and raw clients
+
+Both health APIs are asynchronous:
+
+```ts
+await this.naming.getServerStatus();
+await this.healthIndicator.isHealthy();
+```
+
+Use `@InjectNacosNamingClient()` and `@InjectNacosConfigClient()` only when an
+underlying SDK API is not exposed by the plugin. The module owns and closes
+both clients.
+
+## Compatibility
+
+| Component | Supported |
+|---|---|
+| Node.js | >= 16 |
+| NestJS | 10.x, 11.x |
+| Nacos Node SDK | `nacos` 2.6.x |
+| Nacos Server | 2.x; tested against 2.5.3 |
+| Nacos Server 3.x / gRPC | Not supported |
+
+The underlying SDK implements the HTTP OpenAPI, not the Nacos 3.x gRPC
+protocol. The plugin rejects `transport: 'grpc'` instead of silently falling
+back. Java is required only to run a local Nacos Server, not by the NestJS
+plugin itself.
+
+## Verify
+
+```bash
+npm ci
+npm run build
+npm test
+```