fixed service examples and readmes

Author: aricart

jetstream/README.md

@@ -1,7 +1,8 @@
-# jetstream
+# JetStream
 
 The jetstream module implements the JetStream protocol functionality for
-JavaScript clients.
+JavaScript clients. JetStream is the NATS persistence engine providing
+streaming, message, and worker queues with At-Least-Once semantics.
 
 To use JetStream simply install this library, and create a `jetstream(nc)` or
 `jetstreamManager(nc)` with a connection provided by your chosen transport

services.md renamed to services/README.md

@@ -1,19 +1,23 @@
-# Services Framework
+# Services
 
-The Services Framework introduces a higher-level API for implementing services
-with NATS. NATS has always been a strong technology on which to build services,
-as they are easy to write, are location and DNS independent and can be scaled up
-or down by simply adding or removing instances of the service.
+The Services module introduces a higher-level API for implementing services with
+NATS. NATS has always been a strong technology on which to build services, as
+they are easy to write, are location and DNS independent and can be scaled up or
+down by simply adding or removing instances of the service.
 
-The Services Framework further streamlines their development by providing
+The services module further streamlines their development by providing
 observability and standardization. The Service Framework allows your services to
 be discovered, queried for status and schema information without additional
 work.
 
+To create services using the services module simply install this library and
+create a `new Svc(nc)`.
+
 ## Creating a Service
 
 ```typescript
-const service = await nc.services.add({
+const svc = new Svc(nc);
+const service = await svc.add({
   name: "max",
   version: "0.0.1",
   description: "returns max number in a request",
@@ -55,7 +59,7 @@ sport a different `ID`.
 To discover services that are running, create a monitoring client:
 
 ```typescript
-const m = nc.services.client();
+const m = svc.client();
 
 // you can ping, request info, and stats information.
 // All the operations return iterators describing the services found.
@@ -76,7 +80,7 @@ await m.stats("max", id);
 ```
 
 For a more elaborate first example see:
-[simple example here](services/examples/01_services.ts)
+[simple example here](examples/01_services.ts)
 
 ## Multiple Endpoints
 
@@ -132,4 +136,4 @@ For those paying attention, you can specify a callback much like in the first
 example, if you don't, the return value of the add endpoint is an iterator.
 
 For a complete example see:
-[multiple endpoints](services/examples/02_multiple_endpoints.ts)
+[multiple endpoints](examples/02_multiple_endpoints.ts)

services/examples/01_services.ts

@@ -13,17 +13,18 @@
  * limitations under the License.
  */
 
+import { connect } from "jsr:@nats-io/[email protected]";
+
+import type { QueuedIterator } from "jsr:@nats-io/[email protected]";
+
 import {
-  connect,
-  JSONCodec,
-  QueuedIterator,
   ServiceError,
   ServiceErrorCodeHeader,
   ServiceErrorHeader,
-  ServiceMsg,
-  ServiceStats,
-} from "../../src/mod.ts";
-import { assertEquals } from "https://deno.land/[email protected]/assert/mod.ts";
+  Svc,
+} from "../src/mod.ts";
+import type { ServiceMsg, ServiceStats } from "../src/mod.ts";
+import { assertEquals } from "jsr:@std/assert";
 
 // connect to NATS on demo.nats.io
 const nc = await connect({ servers: ["demo.nats.io"] });
@@ -40,8 +41,9 @@ const statsHandler = (): Promise<unknown> => {
   return Promise.resolve({ max: maxMax });
 };
 
-// create a service - using the statsHandler and decoder
-const service = await nc.services.add({
+// create a service - using the statsHandler
+const svc = new Svc(nc);
+const service = await svc.add({
   name: "max",
   version: "0.0.1",
   description: "returns max number in a request",
@@ -63,7 +65,6 @@ service.stopped.then((err: Error | null) => {
 // starting the service as an async function so that
 // we can have this example be in a single file
 (async () => {
-  const jc = JSONCodec<number>();
   for await (const r of max) {
     // most of the logic is about validating the input
     // and returning an error to the client if the input
@@ -82,7 +83,7 @@ service.stopped.then((err: Error | null) => {
           `${service.info().name} calculated a response of ${max} from ${a.length} values`,
         );
         // finally we respond with a JSON number payload with the maximum value
-        r.respond(jc.encode(max));
+        r.respond(JSON.stringify(max));
       })
       .catch((err) => {
         // if we are here, the initial processing of the array failed
@@ -95,18 +96,17 @@ service.stopped.then((err: Error | null) => {
         r.respondError(
           (err as ServiceError).code || 400,
           err.message,
-          jc.encode(0),
+          JSON.stringify(0),
         );
       });
   }
 })();
 
 // decoder extracts a JSON payload and expects it to be an array of numbers
 function decoder(r: ServiceMsg): Promise<number[]> {
-  const jc = JSONCodec<number[]>();
   try {
     // decode JSON
-    const a = jc.decode(r.data);
+    const a = r.json();
     // if not an array, this is bad input
     if (!Array.isArray(a)) {
       return Promise.reject(
@@ -145,7 +145,7 @@ await nc.request("max").then((r) => {
   assertEquals(r.headers?.get(ServiceErrorCodeHeader), "400");
 });
 // call it with an empty array also expecting an error response
-await nc.request("max", JSONCodec().encode([])).then((r) => {
+await nc.request("max", JSON.stringify([])).then((r) => {
   // Here's an alternative way of checking if the response is an error response
   assertEquals(ServiceError.isServiceError(r), true);
   const se = ServiceError.toServiceError(r);
@@ -154,12 +154,12 @@ await nc.request("max", JSONCodec().encode([])).then((r) => {
 });
 
 // call it with valid arguments
-await nc.request("max", JSONCodec().encode([1, 10, 100])).then((r) => {
+await nc.request("max", JSON.stringify([1, 10, 100])).then((r) => {
   // no error headers
   assertEquals(ServiceError.isServiceError(r), false);
   // and the response is on the payload, so we process the JSON we
   // got from the service
-  assertEquals(JSONCodec().decode(r.data), 100);
+  assertEquals(r.json<number>(), 100);
 });
 
 // Monitoring
@@ -177,7 +177,7 @@ async function collect<T>(p: Promise<QueuedIterator<T>>): Promise<T[]> {
   return buf;
 }
 
-const m = nc.services.client();
+const m = svc.client();
 // discover
 const found = await collect(m.ping());
 assertEquals(found.length, 1);
@@ -199,10 +199,9 @@ await collect(m.stats("max", found[0].id));
 // The id is also optional, but you must know it (from ping or one of
 // other requests that allowed you to discover the service) to
 // target the service specifically as we do here:
-const stats = JSONCodec<ServiceStats>().decode(
-  // note the name of the service matches in case what was specified
-  (await nc.request(`$SRV.STATS.max.${found[0].id}`)).data,
-);
+const r = await nc.request(`$SRV.STATS.max.${found[0].id}`);
+const stats = r.json<ServiceStats>();
+
 assertEquals(stats.name, "max");
 assertEquals(stats.endpoints?.[0].num_requests, 3);
 assertEquals((stats.endpoints?.[0].data as { max: number }).max, 100);

services/examples/02_multiple_endpoints.ts

@@ -13,15 +13,16 @@
  * limitations under the License.
  */
 
-import { connect, JSONCodec, ServiceError, ServiceMsg } from "../../src/mod.ts";
-
-const jc = JSONCodec();
+import { connect } from "jsr:@nats-io/[email protected]";
+import { ServiceError, Svc } from "../src/mod.ts";
+import type { ServiceMsg } from "../src/mod.ts";
 
 // connect to NATS on demo.nats.io
 const nc = await connect({ servers: ["demo.nats.io"] });
 
 // create a service - using the statsHandler and decoder
-const calc = await nc.services.add({
+const svc = new Svc(nc);
+const calc = await svc.add({
   name: "calc",
   version: "0.0.1",
   description: "example calculator service",
@@ -61,7 +62,7 @@ const sums = g.addEndpoint("sum", {
     const s = numbers.reduce((sum, v) => {
       return sum + v;
     });
-    m.respond(jc.encode(s));
+    m.respond(JSON.stringify(s));
   }
 })().then();
 
@@ -76,7 +77,7 @@ g.addEndpoint("average", {
     const sum = numbers.reduce((sum, v) => {
       return sum + v;
     });
-    m.respond(jc.encode(sum / numbers.length));
+    m.respond(JSON.stringify(sum / numbers.length));
   },
   metadata: {
     "input": "JSON number array",
@@ -95,7 +96,7 @@ g.addEndpoint("min", {
     const min = numbers.reduce((n, v) => {
       return Math.min(n, v);
     });
-    m.respond(jc.encode(min));
+    m.respond(JSON.stringify(min));
   },
   metadata: {
     "input": "JSON number array",
@@ -113,7 +114,7 @@ g.addEndpoint("max", {
     const max = numbers.reduce((n, v) => {
       return Math.max(n, v);
     });
-    m.respond(jc.encode(max));
+    m.respond(JSON.stringify(max));
   },
   metadata: {
     "input": "JSON number array",
@@ -127,7 +128,7 @@ calc.stopped.then((err: Error | null) => {
 
 // Now we switch gears and look at a client making a request
 async function calculate(op: string, a: number[]): Promise<void> {
-  const r = await nc.request(`calc.${op}`, jc.encode(a));
+  const r = await nc.request(`calc.${op}`, JSON.stringify(a));
   if (ServiceError.isServiceError(r)) {
     console.log(ServiceError.toServiceError(r));
     return;

services/examples/03_bigdata-client.ts

@@ -12,8 +12,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { parse } from "https://deno.land/[email protected]/flags/mod.ts";
-import { connect, ConnectionOptions, RequestStrategy } from "../../src/mod.ts";
+import { parse } from "jsr:@std/flags";
+import {
+  connect,
+  RequestStrategy,
+} from "jsr:@nats-io/[email protected]";
+import type { ConnectionOptions } from "jsr:@nats-io/[email protected]";
+
 import { humanizeBytes } from "./03_util.ts";
 
 const argv = parse(
@@ -25,7 +30,7 @@ const argv = parse(
       "c": ["chunk"],
     },
     default: {
-      s: "127.0.0.1:4222",
+      s: "demo.nats.io",
       c: 0,
       a: 1024 * 1024,
     },

services/examples/03_bigdata.ts

@@ -13,11 +13,14 @@
  * limitations under the License.
  */
 
-import { connect } from "../../src/mod.ts";
-import { DataRequest, humanizeBytes } from "./03_util.ts";
+import { connect } from "jsr:@nats-io/[email protected]";
+import { Svc } from "../src/mod.ts";
+import { humanizeBytes } from "./03_util.ts";
+import type { DataRequest } from "./03_util.ts";
 
-const nc = await connect();
-const srv = await nc.services.add({
+const nc = await connect({ servers: "demo.nats.io" });
+const svc = new Svc(nc);
+const srv = await svc.add({
   name: "big-data",
   version: "0.0.1",
 });

services/src/types.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   Msg,
   Nanos,
   NatsError,

services/tests/service-check.ts

@@ -15,12 +15,9 @@
 
 import { cli } from "https://deno.land/x/[email protected]/mod.ts";
 import { connect } from "jsr:@nats-io/[email protected]";
-import {
-  collect,
-  NatsConnection,
-  parseSemVer,
-  StringCodec,
-} from "@nats-io/nats-core/internal";
+import { collect, parseSemVer, StringCodec } from "@nats-io/nats-core/internal";
+
+import type { NatsConnection } from "@nats-io/nats-core/internal";
 
 import type { ServiceIdentity, ServiceInfo, ServiceStats } from "../src/mod.ts";
 import {