Simple config and opt-in namespaces (#90)

* Removing createConfig, allowing empty argument for Config::constructor.

* Fix compatibility test.

* Test for no namespaces.

* REF: introducing createSimpleConfig() and removing fallback from Config.

* Update README.md

* Update README.md

* Upd compat test.

* Upd config test.

* Update src/config.ts

* Changelog: 0.13.0.

* Shortening.

Author: RobinTail

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Version 0
 
+### v0.13.0
+
+- Config creation changes aim to improve the clarity and make it easier to begin using this library for the first time;
+- Easier config for a simple applications:
+  - Replacing `createConfig()` with `createSimpleConfig()` - for a single namespace (root namespace only).
+- Making namespaces opt-in feature:
+  - Use the exposed `new Config()` and its `.addNamespace()` method of each namespace;
+  - Fallbacks removed from `Config::constructor` — it creates no namespaces by default,
+    but `addNamespace` creates root namespace when `path` prop is omitted;
+- See the migration advice below.
+
+```ts
+// if using the root namespace only:
+import { createSimpleConfig } from "zod-sockets";
+const simpleConfig = createSimpleConfig({
+  /* logger, timeout, emission, hooks, metadata */
+});
+
+// if using namespaces other than "/":
+import { Config } from "zod-sockets";
+const config = new Config({ logger, timeout })
+  .addNamespace({
+    path: "ns1",
+    /* emission, hooks, metadata */
+  })
+  .addNamespace({
+    path: "ns2",
+    /* emission, hooks, metadata */
+  });
+```
+
 ### v0.12.0
 
 - Switching to AsyncAPI version 3.0.0 for generating documentation:

README.md

@@ -43,10 +43,10 @@ yarn add zod-sockets zod socket.io typescript
 ## Set up config
 
 ```typescript
-import { createConfig } from "zod-sockets";
+import { createSimpleConfig } from "zod-sockets";
 
-// defaults: root namespace only, console logger, timeout 2s
-const config = createConfig();
+// shorthand for root namespace only, defaults: console logger, timeout 2s
+const config = createSimpleConfig();
 ```
 
 ## Create a factory
@@ -111,36 +111,6 @@ for sending the `ping` event to `ws://localhost:8090` with acknowledgement.
 
 # Basic features
 
-## Namespaces first
-
-Namespaces allow you to separate incoming and outgoing events into groups, in which events can have the same name, but
-different essence, payload and handlers. You can add `namespaces` to the argument of `createConfig()` or use
-`addNamespace()` method after it. The default namespace is a root one having `path` equal to `/`. Namespaces may have
-`emission` and `hooks`.
-Read the Socket.IO [documentation on namespaces](https://socket.io/docs/v4/namespaces/).
-
-```typescript
-import { createConfig } from "zod-sockets";
-
-const config = createConfig({
-  namespaces: {
-    // The namespace "/public"
-    public: {
-      emission: { chat: { schema } },
-      hooks: {
-        onStartup: () => {},
-        onConnection: () => {},
-        onDisconnect: () => {},
-        onAnyIncoming: () => {},
-        onAnyOutgoing: () => {},
-      },
-    },
-  },
-}).addNamespace({
-  path: "private", // The namespace "/private" has no emission
-});
-```
-
 ## Emission
 
 The outgoing events should be configured using `z.tuple()` schemas. Those tuples describe the types of the arguments
@@ -151,10 +121,9 @@ development. Consider the following examples of two outgoing events, with and wi
 
 ```typescript
 import { z } from "zod";
-import { createConfig } from "zod-sockets";
+import { createSimpleConfig } from "zod-sockets";
 
-const config = createConfig().addNamespace({
-  // path: "/", // optional, default: root namespace
+const config = createSimpleConfig({
   emission: {
     // enabling Socket::emit("chat", "message", { from: "someone" })
     chat: {
@@ -222,15 +191,15 @@ The library supports any logger having `info()`, `debug()`, `error()` and
 
 ```typescript
 import pino, { Logger } from "pino";
-import { createConfig } from "zod-sockets";
+import { createSimpleConfig } from "zod-sockets";
 
 const logger = pino({
   transport: {
     target: "pino-pretty",
     options: { colorize: true },
   },
 });
-const config = createConfig({ logger });
+const config = createSimpleConfig({ logger });
 
 // Setting the type of logger used
 declare module "zod-sockets" {
@@ -241,16 +210,16 @@ declare module "zod-sockets" {
 ### With Express Zod API
 
 If you're using `express-zod-api`, you can reuse the same logger. If it's a custom logger — supply the same instance to
-both `createConfig()` methods of two libraries. In case you're using the default `winston` logger provided by
+configs of both libraries. In case you're using the default `winston` logger provided by
 `express-zod-api`, you can obtain its instance from the returns of the `createServer()` method.
 
 ```typescript
 import { createServer } from "express-zod-api";
-import { createConfig } from "zod-sockets";
+import { createSimpleConfig } from "zod-sockets";
 import type { Logger } from "winston";
 
 const { logger } = await createServer();
-const config = createConfig({ logger });
+const config = createSimpleConfig({ logger });
 
 // Setting the type of logger used
 declare module "zod-sockets" {
@@ -342,9 +311,9 @@ emit events regardless the incoming ones by setting the `onConnection` property
 argument, which has a similar interface except `input` and fires for every connected client:
 
 ```typescript
-import { createConfig } from "zod-sockets";
+import { createSimpleConfig } from "zod-sockets";
 
-const config = createConfig().addNamespace({
+const config = createSimpleConfig({
   // emission: { ... },
   hooks: {
     onConnection: async ({ client, withRooms, all }) => {
@@ -360,9 +329,9 @@ Moreover, you can emit events regardless the client activity at all by setting t
 of the `addNamespace()` argument. The implementation may have a `setInterval()` for recurring emission.
 
 ```typescript
-import { createConfig } from "zod-sockets";
+import { createSimpleConfig } from "zod-sockets";
 
-const config = createConfig().addNamespace({
+const config = createSimpleConfig({
   hooks: {
     onStartup: async ({ all, withRooms }) => {
       // sending to everyone in a room
@@ -440,9 +409,9 @@ Please avoid transformations in those schemas since they are not going to be app
 
 ```typescript
 import { z } from "zod";
-import { createConfig } from "zod-sockets";
+import { createSimpleConfig } from "zod-sockets";
 
-const config = createConfig().addNamespace({
+const config = createSimpleConfig({
   metadata: z.object({
     /** @desc Number of messages sent to the chat */
     msgCount: z.number().int(),
@@ -475,6 +444,36 @@ const handler = async ({ client }) => {
 };
 ```
 
+## Namespaces
+
+Namespaces allow you to separate incoming and outgoing events into groups, in which events can have the same name, but
+different essence, payload and handlers. For using namespaces replace the `createSimpleConfig()` method with
+`new Config()`, then use its `.addNamespace()` method for each namespace. Namespaces may have `emission` and `hooks`.
+Read the Socket.IO [documentation on namespaces](https://socket.io/docs/v4/namespaces/).
+
+```typescript
+import { Config } from "zod-sockets";
+
+const config = new Config({
+  logger,
+  timeout: 2000,
+})
+  .addNamespace({
+    // The namespace "/public"
+    emission: { chat: { schema } },
+    hooks: {
+      onStartup: () => {},
+      onConnection: () => {},
+      onDisconnect: () => {},
+      onAnyIncoming: () => {},
+      onAnyOutgoing: () => {},
+    },
+  })
+  .addNamespace({
+    path: "private", // The namespace "/private" has no emission
+  });
+```
+
 # Integration
 
 ## Exporting types for frontend

example/config.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { createConfig } from "../src";
+import { createSimpleConfig } from "../src";
 
-export const config = createConfig().addNamespace({
+export const config = createSimpleConfig({
   emission: {
     time: {
       schema: z.tuple([

src/actions-factory.spec.ts

@@ -2,17 +2,10 @@ import { describe, expect, test, vi } from "vitest";
 import { z } from "zod";
 import { Action } from "./action";
 import { ActionsFactory } from "./actions-factory";
-import { createConfig } from "./config";
-import { AbstractLogger } from "./logger";
+import { createSimpleConfig } from "./config";
 
 describe("ActionsFactory", () => {
-  const factory = new ActionsFactory(
-    createConfig({
-      namespaces: {},
-      timeout: 2000,
-      logger: { debug: vi.fn() } as unknown as AbstractLogger,
-    }),
-  );
+  const factory = new ActionsFactory(createSimpleConfig());
 
   describe("constructor", () => {
     test("should create a factory", () => {
@@ -24,7 +17,7 @@ describe("ActionsFactory", () => {
         factory.build({
           event: "test",
           input: z.tuple([z.string()]),
-          handler: vi.fn(),
+          handler: vi.fn<any>(),
         }),
       ).toBeInstanceOf(Action);
     });

src/attach.spec.ts

@@ -3,7 +3,7 @@ import { Server } from "socket.io";
 import { describe, expect, test, vi } from "vitest";
 import { z } from "zod";
 import { attachSockets } from "./attach";
-import { createConfig } from "./config";
+import { createSimpleConfig } from "./config";
 import { AbstractLogger } from "./logger";
 
 describe("Attach", () => {
@@ -67,16 +67,12 @@ describe("Attach", () => {
         io: ioMock as unknown as Server,
         target: targetMock as unknown as http.Server,
         actions: actionsMock,
-        config: createConfig({
+        config: createSimpleConfig({
           startupLogo: false,
           timeout: 100,
-          namespaces: {
-            "/": {
-              emission: {},
-              hooks,
-              metadata: z.object({ name: z.string() }),
-            },
-          },
+          emission: {},
+          hooks,
+          metadata: z.object({ name: z.string() }),
           logger: loggerMock as unknown as AbstractLogger,
         }),
       });

src/config.spec.ts

@@ -1,46 +1,44 @@
 import { describe, expect, test, vi } from "vitest";
 import { z } from "zod";
-import { Config, createConfig } from "./config";
+import { Config, createSimpleConfig } from "./config";
 import { AbstractLogger } from "./logger";
 
 describe("Config", () => {
-  describe("createConfig()", () => {
+  describe("::constructor", () => {
     test("should create config without any argument", () => {
-      const config = createConfig();
+      const config = new Config();
       expect(config).toBeInstanceOf(Config);
       expect(config.logger).toEqual(console);
       expect(config.timeout).toBe(2000);
-      expect(config.namespaces).toEqual({
-        "/": { emission: {}, hooks: {}, metadata: expect.any(z.ZodObject) },
-      });
+      expect(config.namespaces).toEqual({});
     });
 
     test("should create the class instance from the definition", () => {
-      const config = createConfig({
+      const config = new Config({
         namespaces: {
           "/": { emission: {}, hooks: {}, metadata: z.object({}) },
           test: { emission: {}, hooks: {}, metadata: z.object({}) },
         },
-        timeout: 2000,
+        timeout: 3000,
         logger: { debug: vi.fn() } as unknown as AbstractLogger,
       });
       expect(config).toBeInstanceOf(Config);
       expect(config.logger).toEqual({ debug: expect.any(Function) });
-      expect(config.timeout).toBe(2000);
+      expect(config.timeout).toBe(3000);
       expect(config.namespaces).toEqual({
         "/": { emission: {}, hooks: {}, metadata: expect.any(z.ZodObject) },
         test: { emission: {}, hooks: {}, metadata: expect.any(z.ZodObject) },
       });
     });
+  });
 
-    test("should set defaults and provide namespace augmentation method", () => {
-      const base = createConfig({});
+  describe(".addNamespace()", () => {
+    test("should provide namespace augmentation method", () => {
+      const base = new Config();
       expect(base).toBeInstanceOf(Config);
       expect(base.logger).toEqual(console);
       expect(base.timeout).toBe(2000);
-      expect(base.namespaces).toEqual({
-        "/": { emission: {}, hooks: {}, metadata: expect.any(z.ZodObject) },
-      });
+      expect(base.namespaces).toEqual({});
       const schema = z.tuple([]);
       const config = base.addNamespace({
         path: "/",
@@ -56,4 +54,32 @@ describe("Config", () => {
       });
     });
   });
+
+  describe("createSimpleConfig()", () => {
+    test("should set defaults", () => {
+      const config = createSimpleConfig();
+      expect(config).toBeInstanceOf(Config);
+      expect(config.logger).toEqual(console);
+      expect(config.timeout).toBe(2000);
+      expect(config.namespaces).toEqual({
+        "/": { emission: {}, hooks: {}, metadata: expect.any(z.ZodObject) },
+      });
+    });
+
+    test("should set the root namespace properties", () => {
+      const config = createSimpleConfig({
+        timeout: 3000,
+        logger: { debug: vi.fn() } as unknown as AbstractLogger,
+        emission: {},
+        hooks: {},
+        metadata: z.object({}),
+      });
+      expect(config).toBeInstanceOf(Config);
+      expect(config.logger).not.toEqual(console);
+      expect(config.timeout).toBe(3000);
+      expect(config.namespaces).toEqual({
+        "/": { emission: {}, hooks: {}, metadata: expect.any(z.ZodObject) },
+      });
+    });
+  });
 });