@voidhash/mimic-effect 0.0.3 → 0.0.5

package/src/MimicServer.ts

@@ -20,20 +20,6 @@ import * as NoAuth from "./auth/NoAuth.js";
 import { HttpLayerRouter, HttpServerRequest, HttpServerResponse } from "@effect/platform";
 import { PathInput } from "@effect/platform/HttpRouter";
 
-// =============================================================================
-// Handler Tag
-// =============================================================================
-
-/**
- * Tag for the WebSocket handler function.
- */
-export class MimicWebSocketHandler extends Context.Tag(
-  "@voidhash/mimic-server-effect/MimicWebSocketHandler"
-)<
-  MimicWebSocketHandler,
-  (socket: Socket.Socket, documentId: string) => Effect.Effect<void, unknown>
->() {}
-
 // =============================================================================
 // Layer Composition Options
 // =============================================================================
@@ -41,7 +27,9 @@ export class MimicWebSocketHandler extends Context.Tag(
 /**
  * Options for creating a Mimic server layer.
  */
-export interface MimicLayerOptions<TSchema extends Primitive.AnyPrimitive> {
+export interface MimicLayerOptions<
+  TSchema extends Primitive.AnyPrimitive,
+> {
   /**
    * Base path for document routes (used for path matching).
    * @example "/mimic/todo" - documents accessed at "/mimic/todo/:documentId"
@@ -61,121 +49,23 @@ export interface MimicLayerOptions<TSchema extends Primitive.AnyPrimitive> {
    * When provided, enables presence features on WebSocket connections.
    */
   readonly presence?: Presence.AnyPresence;
+  /**
+   * Initial state for new documents.
+   * Can be either:
+   * - A plain object with the initial state values
+   * - A function that receives context (with documentId) and returns an Effect producing the initial state
+   *
+   * When using a function that requires Effect services (has R requirements),
+   * you must also provide `initialLayer` to supply those dependencies.
+   *
+   * Type-safe: required fields (without defaults) must be provided,
+   * while optional fields and fields with defaults can be omitted.
+   *
+   * @default undefined (documents start empty or use schema defaults)
+   */
+  readonly initial?: Primitive.InferSetInput<TSchema> | MimicConfig.InitialFn<TSchema>;
 }
 
-// =============================================================================
-// Layer Composition
-// =============================================================================
-
-/**
- * Create a Mimic WebSocket handler layer.
- * 
- * This layer provides a handler function that can be used with any WebSocket server
- * implementation. The handler takes a socket and document ID and manages the
- * document synchronization.
- * 
- * By default, uses in-memory storage and no authentication.
- * Override these by providing MimicDataStorage and MimicAuthService layers.
- * 
- * @example
- * ```typescript
- * import { MimicServer, MimicAuthService } from "@voidhash/mimic-effect";
- * import { Primitive } from "@voidhash/mimic";
- * 
- * const TodoSchema = Primitive.Struct({
- *   title: Primitive.String(),
- *   completed: Primitive.Boolean(),
- * });
- * 
- * // Create the handler layer with defaults
- * const HandlerLayer = MimicServer.layer({
- *   basePath: "/mimic/todo",
- *   schema: TodoSchema
- * });
- * 
- * // Or with custom auth
- * const HandlerLayerWithAuth = MimicServer.layer({
- *   basePath: "/mimic/todo",
- *   schema: TodoSchema
- * }).pipe(
- *   Layer.provideMerge(MimicAuthService.layer({
- *     authHandler: (token) => ({ success: true, userId: "user-123" })
- *   }))
- * );
- * ```
- */
-export const layer = <TSchema extends Primitive.AnyPrimitive>(
-  options: MimicLayerOptions<TSchema>
-): Layer.Layer<MimicWebSocketHandler | DocumentManager.DocumentManagerTag> => {
-  const configLayer = MimicConfig.layer({
-    schema: options.schema,
-    maxTransactionHistory: options.maxTransactionHistory,
-    presence: options.presence,
-  });
-
-  return Layer.merge(
-    // Handler layer
-    Layer.effect(MimicWebSocketHandler, WebSocketHandler.makeHandler).pipe(
-      Layer.provide(DocumentManager.layer),
-      Layer.provide(PresenceManager.layer),
-      Layer.provide(configLayer)
-    ),
-    // Document manager layer
-    DocumentManager.layer.pipe(Layer.provide(configLayer))
-  ).pipe(
-    // Provide defaults if not overridden
-    Layer.provide(InMemoryDataStorage.layerDefault),
-    Layer.provide(NoAuth.layerDefault)
-  );
-};
-
-/**
- * Create the Mimic server handler layer.
- * This layer provides the WebSocket handler that can be used with any WebSocket server.
- *
- * @example
- * ```typescript
- * import { MimicServer } from "@voidhash/mimic-server-effect";
- * import { SocketServer } from "@effect/platform/SocketServer";
- * import { Primitive } from "@voidhash/mimic";
- *
- * // Define your document schema
- * const TodoSchema = Primitive.Struct({
- *   title: Primitive.String(),
- *   completed: Primitive.Boolean(),
- * });
- *
- * // Create the server layer
- * const serverLayer = MimicServer.handlerLayer({
- *   schema: TodoSchema,
- * });
- *
- * // Run with your socket server
- * Effect.gen(function* () {
- *   const handler = yield* MimicServer.MimicWebSocketHandler;
- *   const server = yield* SocketServer;
- *
- *   yield* server.run((socket) =>
- *     // Extract document ID from request and call handler
- *     handler(socket, "my-document-id")
- *   );
- * }).pipe(
- *   Effect.provide(serverLayer),
- *   Effect.provide(YourSocketServerLayer),
- * );
- * ```
- */
-export const handlerLayer = <TSchema extends Primitive.AnyPrimitive>(
-  options: MimicConfig.MimicServerConfigOptions<TSchema>
-): Layer.Layer<MimicWebSocketHandler> =>
-  Layer.effect(MimicWebSocketHandler, WebSocketHandler.makeHandler).pipe(
-    Layer.provide(DocumentManager.layer),
-    Layer.provide(PresenceManager.layer),
-    Layer.provide(MimicConfig.layer(options)),
-    // Provide defaults
-    Layer.provide(InMemoryDataStorage.layerDefault),
-    Layer.provide(NoAuth.layerDefault)
-  );
 
 /**
  * Create the document manager layer.
@@ -190,40 +80,6 @@ export const documentManagerLayer = <TSchema extends Primitive.AnyPrimitive>(
     Layer.provide(NoAuth.layerDefault)
   );
 
-// =============================================================================
-// Convenience Functions
-// =============================================================================
-
-/**
- * Run a Mimic WebSocket server with the provided handler.
- *
- * This is a helper that:
- * 1. Gets the WebSocket handler from context
- * 2. Runs the socket server with the handler
- *
- * Note: The document ID extraction from socket is implementation-specific.
- * You may need to customize this based on your socket server.
- */
-export const run = (
-  extractDocumentId: (socket: Socket.Socket) => Effect.Effect<string>
-) =>
-  Effect.gen(function* () {
-    const handler = yield* MimicWebSocketHandler;
-    const server = yield* SocketServer;
-
-    yield* server.run((socket) =>
-      Effect.gen(function* () {
-        const documentId = yield* extractDocumentId(socket);
-        yield* handler(socket, documentId);
-      }).pipe(
-        Effect.catchAll((error) =>
-          Effect.logError("Connection error", error)
-        )
-      )
-    );
-  });
-
-
 /**
  * Create the HTTP handler effect for WebSocket upgrade.
  * This handler:
@@ -275,6 +131,17 @@ const makeMimicHandler = Effect.gen(function* () {
 
 
 
+/**
+ * Options for layerHttpLayerRouter including optional custom layers.
+ */
+export interface MimicLayerRouterOptions<TSchema extends Primitive.AnyPrimitive>
+  extends MimicLayerOptions<TSchema> {
+  /** Custom auth layer. Defaults to NoAuth (all connections allowed). */
+  readonly authLayer?: Layer.Layer<MimicAuthServiceTag>;
+  /** Custom storage layer. Defaults to InMemoryDataStorage. */
+  readonly storageLayer?: Layer.Layer<MimicDataStorageTag>;
+}
+
 /**
  * Create a Mimic server layer that integrates with HttpLayerRouter.
  *
@@ -321,43 +188,52 @@ const makeMimicHandler = Effect.gen(function* () {
  * );
  * ```
  */
-export const layerHttpLayerRouter = <TSchema extends Primitive.AnyPrimitive>(
-  options: MimicLayerOptions<TSchema> & {
-    /** Custom auth layer. Defaults to NoAuth (all connections allowed). */
-    readonly authLayer?: Layer.Layer<MimicAuthServiceTag>;
-    /** Custom storage layer. Defaults to InMemoryDataStorage. */
-    readonly storageLayer?: Layer.Layer<MimicDataStorageTag>;
-  }
-) => {
-  // Build the base path pattern for WebSocket routes
-  // Append /doc/* to match /basePath/doc/{documentId}
-  const basePath = options.basePath ?? "/mimic";
-  const wsPath: PathInput = `${basePath}/doc/*` as PathInput;
-
-  // Create the config layer
-  const configLayer = MimicConfig.layer({
-    schema: options.schema,
-    maxTransactionHistory: options.maxTransactionHistory,
-    presence: options.presence,
-  });
-
-  // Use provided layers or defaults
-  const authLayer = options.authLayer ?? NoAuth.layerDefault;
-  const storageLayer = options.storageLayer ?? InMemoryDataStorage.layerDefault;
-
-  // Create the route registration effect
-  const registerRoute = Effect.gen(function* () {
-    const router = yield* HttpLayerRouter.HttpRouter;
-    const handler = yield* makeMimicHandler;
-    yield* router.add("GET", wsPath, handler);
-  });
-
-  // Build the layer with all dependencies
-  return Layer.scopedDiscard(registerRoute).pipe(
-    Layer.provide(DocumentManager.layer),
-    Layer.provide(PresenceManager.layer),
-    Layer.provide(configLayer),
-    Layer.provide(storageLayer),
-    Layer.provide(authLayer)
+export const layerHttpLayerRouter = <
+  TSchema extends Primitive.AnyPrimitive,
+  TError,
+  TRequirements
+>(
+  optionsEf: Effect.Effect<MimicLayerRouterOptions<TSchema>, TError, TRequirements>
+): Layer.Layer<never, TError, TRequirements | HttpLayerRouter.HttpRouter> => {
+  return Layer.unwrapScoped(
+    Effect.gen(function* () {
+      const options = yield* optionsEf;
+
+      // Build the base path pattern for WebSocket routes
+      // Append /doc/* to match /basePath/doc/{documentId}
+      const basePath = options.basePath ?? "/mimic";
+      const wsPath: PathInput = `${basePath}/doc/*` as PathInput;
+
+      // Create the config layer with properly typed initial function
+      const configLayer = MimicConfig.layer<TSchema>({
+        schema: options.schema,
+        maxTransactionHistory: options.maxTransactionHistory,
+        presence: options.presence,
+        initial: options.initial,
+      });
+
+      // Use provided layers or defaults
+      const authLayer = options.authLayer ?? NoAuth.layerDefault;
+      const storageLayer = options.storageLayer ?? InMemoryDataStorage.layerDefault;
+
+      // Combine all dependency layers
+      const depsLayer = Layer.mergeAll(configLayer, authLayer, storageLayer);
+
+      // Create the route registration layer
+      const routeLayer = Layer.scopedDiscard(
+        Effect.gen(function* () {
+          const router = yield* HttpLayerRouter.HttpRouter;
+          const handler = yield* makeMimicHandler;
+          yield* router.add("GET", wsPath, handler);
+        })
+      );
+
+      // Build the complete layer with all dependencies provided
+      return routeLayer.pipe(
+        Layer.provide(DocumentManager.layer),
+        Layer.provide(PresenceManager.layer),
+        Layer.provide(depsLayer),
+      );
+    })
   );
 };

package/tests/DocumentManager.test.ts

@@ -337,4 +337,128 @@ describe("DocumentManager", () => {
       expect(result).toBe(true);
     });
   });
+
+  describe("initial state", () => {
+    const makeTestLayerWithInitial = (initial: { title?: string; count?: number }) => {
+      const configLayer = MimicConfig.layer({
+        schema: TestSchema,
+        maxTransactionHistory: 100,
+        initial,
+      });
+
+      return DocumentManager.layer.pipe(
+        Layer.provide(configLayer),
+        Layer.provide(InMemoryDataStorage.layer)
+      );
+    };
+
+    const makeTestLayerWithInitialFn = (
+      initialFn: (ctx: { documentId: string }) => Effect.Effect<{ title?: string; count?: number }>
+    ) => {
+      const configLayer = MimicConfig.layer({
+        schema: TestSchema,
+        maxTransactionHistory: 100,
+        initial: initialFn,
+      });
+
+      return DocumentManager.layer.pipe(
+        Layer.provide(configLayer),
+        Layer.provide(InMemoryDataStorage.layer)
+      );
+    };
+
+    it("should use initial state for new documents", async () => {
+      const result = await Effect.runPromise(
+        Effect.gen(function* () {
+          const manager = yield* DocumentManager.DocumentManagerTag;
+          return yield* manager.getSnapshot("new-doc");
+        }).pipe(Effect.provide(makeTestLayerWithInitial({ title: "Initial Title", count: 42 })))
+      );
+
+      expect(result.type).toBe("snapshot");
+      expect(result.version).toBe(0);
+      expect(result.state).toEqual({ title: "Initial Title", count: 42 });
+    });
+
+    it("should apply defaults for omitted fields in initial state", async () => {
+      const result = await Effect.runPromise(
+        Effect.gen(function* () {
+          const manager = yield* DocumentManager.DocumentManagerTag;
+          return yield* manager.getSnapshot("new-doc");
+        }).pipe(Effect.provide(makeTestLayerWithInitial({ title: "Only Title" })))
+      );
+
+      expect(result.type).toBe("snapshot");
+      // count should be 0 (default)
+      expect(result.state).toEqual({ title: "Only Title", count: 0 });
+    });
+
+    it("should prefer stored state over initial state", async () => {
+      const result = await Effect.runPromise(
+        Effect.gen(function* () {
+          const manager = yield* DocumentManager.DocumentManagerTag;
+
+          // Apply a transaction to modify the document
+          const tx = createValidTransaction("tx-1", "Modified Title");
+          yield* manager.submit("doc-1", tx);
+
+          // Get snapshot - should show modified state, not initial
+          return yield* manager.getSnapshot("doc-1");
+        }).pipe(Effect.provide(makeTestLayerWithInitial({ title: "Initial Title", count: 42 })))
+      );
+
+      expect(result.type).toBe("snapshot");
+      expect((result.state as any).title).toBe("Modified Title");
+      // count should still be 42 since we only modified title
+      expect((result.state as any).count).toBe(42);
+    });
+
+    it("should use initial state function with documentId for new documents", async () => {
+      const result = await Effect.runPromise(
+        Effect.gen(function* () {
+          const manager = yield* DocumentManager.DocumentManagerTag;
+          return yield* manager.getSnapshot("my-special-doc");
+        }).pipe(Effect.provide(makeTestLayerWithInitialFn(
+          ({ documentId }) => Effect.succeed({ title: `Doc: ${documentId}`, count: documentId.length })
+        )))
+      );
+
+      expect(result.type).toBe("snapshot");
+      expect(result.version).toBe(0);
+      expect(result.state).toEqual({ title: "Doc: my-special-doc", count: 14 });
+    });
+
+    it("should call initial function with different documentIds", async () => {
+      const layer = makeTestLayerWithInitialFn(
+        ({ documentId }) => Effect.succeed({ title: documentId, count: documentId.length })
+      );
+
+      const result = await Effect.runPromise(
+        Effect.gen(function* () {
+          const manager = yield* DocumentManager.DocumentManagerTag;
+          const snap1 = yield* manager.getSnapshot("short");
+          const snap2 = yield* manager.getSnapshot("longer-document-id");
+          return { snap1, snap2 };
+        }).pipe(Effect.provide(layer))
+      );
+
+      expect(result.snap1.state).toEqual({ title: "short", count: 5 });
+      expect(result.snap2.state).toEqual({ title: "longer-document-id", count: 18 });
+    });
+
+    it("should apply defaults to initial function result", async () => {
+      const result = await Effect.runPromise(
+        Effect.gen(function* () {
+          const manager = yield* DocumentManager.DocumentManagerTag;
+          return yield* manager.getSnapshot("test-doc");
+        }).pipe(Effect.provide(makeTestLayerWithInitialFn(
+          ({ documentId }) => Effect.succeed({ title: documentId }) // count omitted
+        )))
+      );
+
+      expect(result.type).toBe("snapshot");
+      // count should be 0 (default)
+      expect(result.state).toEqual({ title: "test-doc", count: 0 });
+    });
+  });
 });

package/tests/MimicConfig.test.ts

@@ -172,4 +172,119 @@ describe("MimicConfig", () => {
       expect(config.presence).toBe(CursorPresence);
     });
   });
+
+  describe("initial state configuration", () => {
+    it("should have undefined initial state by default", () => {
+      const config = MimicConfig.make({
+        schema: TestSchema,
+      });
+
+      expect(config.initial).toBeUndefined();
+    });
+
+    it("should accept initial state object and convert to function", async () => {
+      const config = MimicConfig.make({
+        schema: TestSchema,
+        initial: { title: "My Document", count: 42 },
+      });
+
+      expect(typeof config.initial).toBe("function");
+      // The function should return the initial state when called
+      const result = await Effect.runPromise(config.initial!({ documentId: "test-doc" }));
+      expect(result).toEqual({ title: "My Document", count: 42 });
+    });
+
+    it("should apply defaults for omitted fields in initial state object", async () => {
+      const config = MimicConfig.make({
+        schema: TestSchema,
+        initial: { title: "My Document" }, // count has default of 0
+      });
+
+      const result = await Effect.runPromise(config.initial!({ documentId: "test-doc" }));
+      expect(result).toEqual({ title: "My Document", count: 0 });
+    });
+
+    it("should accept initial state function", async () => {
+      const config = MimicConfig.make({
+        schema: TestSchema,
+        initial: ({ documentId }) => Effect.succeed({ title: `Doc ${documentId}`, count: 123 }),
+      });
+
+      expect(typeof config.initial).toBe("function");
+      const result = await Effect.runPromise(config.initial!({ documentId: "my-doc-id" }));
+      expect(result).toEqual({ title: "Doc my-doc-id", count: 123 });
+    });
+
+    it("should apply defaults to initial state function result", async () => {
+      const config = MimicConfig.make({
+        schema: TestSchema,
+        initial: ({ documentId }) => Effect.succeed({ title: documentId }), // count omitted
+      });
+
+      const result = await Effect.runPromise(config.initial!({ documentId: "test" }));
+      expect(result).toEqual({ title: "test", count: 0 });
+    });
+
+    it("should provide initial function through layer", async () => {
+      const testLayer = MimicConfig.layer({
+        schema: TestSchema,
+        initial: { title: "From Layer", count: 100 },
+      });
+
+      const result = await Effect.runPromise(
+        Effect.gen(function* () {
+          const config = yield* MimicConfig.MimicServerConfigTag;
+          return yield* config.initial!({ documentId: "layer-doc" });
+        }).pipe(Effect.provide(testLayer))
+      );
+
+      expect(result).toEqual({ title: "From Layer", count: 100 });
+    });
+
+    it("should work with schema that has required fields without defaults", async () => {
+      const SchemaWithRequired = Primitive.Struct({
+        name: Primitive.String().required(),
+        optional: Primitive.String().default("default"),
+      });
+
+      const config = MimicConfig.make({
+        schema: SchemaWithRequired,
+        initial: { name: "Required Name" },
+      });
+
+      const result = await Effect.runPromise(config.initial!({ documentId: "test" }));
+      expect(result).toEqual({ name: "Required Name", optional: "default" });
+    });
+
+    it("should work with all options including initial object", async () => {
+      const config = MimicConfig.make({
+        schema: TestSchema,
+        maxIdleTime: "10 minutes",
+        maxTransactionHistory: 500,
+        initial: { title: "Full Options", count: 999 },
+      });
+
+      expect(config.schema).toBe(TestSchema);
+      expect(Duration.toMillis(config.maxIdleTime)).toBe(10 * 60 * 1000);
+      expect(config.maxTransactionHistory).toBe(500);
+      const result = await Effect.runPromise(config.initial!({ documentId: "test" }));
+      expect(result).toEqual({ title: "Full Options", count: 999 });
+    });
+
+    it("should work with initial function that uses documentId", async () => {
+      const config = MimicConfig.make({
+        schema: TestSchema,
+        initial: ({ documentId }) => Effect.succeed({
+          title: `Document: ${documentId}`,
+          count: documentId.length,
+        }),
+      });
+
+      const result1 = await Effect.runPromise(config.initial!({ documentId: "short" }));
+      expect(result1).toEqual({ title: "Document: short", count: 5 });
+
+      const result2 = await Effect.runPromise(config.initial!({ documentId: "longer-id" }));
+      expect(result2).toEqual({ title: "Document: longer-id", count: 9 });
+    });
+  });
 });