@voidhash/mimic-effect 0.0.3 → 0.0.4

package/src/MimicConfig.ts

@@ -6,7 +6,7 @@ import * as Context from "effect/Context";
 import * as Duration from "effect/Duration";
 import type { DurationInput } from "effect/Duration";
 import * as Layer from "effect/Layer";
-import type { Primitive, Presence } from "@voidhash/mimic";
+import { Primitive, Presence } from "@voidhash/mimic";
 
 // =============================================================================
 // Mimic Server Configuration
@@ -54,6 +54,13 @@ export interface MimicServerConfig<TSchema extends Primitive.AnyPrimitive = Prim
    * @default undefined (presence disabled)
    */
   readonly presence: Presence.AnyPresence | undefined;
+
+  /**
+   * Initial state for new documents.
+   * Used when a document is created and no existing state is found in storage.
+   * @default undefined (documents start empty)
+   */
+  readonly initial: Primitive.InferState<TSchema> | undefined;
 }
 
 /**
@@ -95,6 +102,17 @@ export interface MimicServerConfigOptions<TSchema extends Primitive.AnyPrimitive
    * @default undefined (presence disabled)
    */
   readonly presence?: Presence.AnyPresence;
+
+  /**
+   * Initial state for new documents.
+   * Used when a document is created and no existing state is found in storage.
+   *
+   * 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>;
 }
 
 /**
@@ -109,6 +127,9 @@ export const make = <TSchema extends Primitive.AnyPrimitive>(
   heartbeatInterval: Duration.decode(options.heartbeatInterval ?? "30 seconds"),
   heartbeatTimeout: Duration.decode(options.heartbeatTimeout ?? "10 seconds"),
   presence: options.presence,
+  initial: options.initial !== undefined
+    ? Primitive.applyDefaults(options.schema, options.initial as Partial<Primitive.InferState<TSchema>>)
+    : undefined,
 });
 
 // =============================================================================

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
 // =============================================================================
@@ -61,121 +47,18 @@ export interface MimicLayerOptions<TSchema extends Primitive.AnyPrimitive> {
    * When provided, enables presence features on WebSocket connections.
    */
   readonly presence?: Presence.AnyPresence;
+  /**
+   * Initial state for new documents.
+   * Used when a document is created and no existing state is found in storage.
+   *
+   * 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>;
 }
 
-// =============================================================================
-// 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 +73,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:
@@ -339,6 +188,7 @@ export const layerHttpLayerRouter = <TSchema extends Primitive.AnyPrimitive>(
     schema: options.schema,
     maxTransactionHistory: options.maxTransactionHistory,
     presence: options.presence,
+    initial: options.initial,
   });
 
   // Use provided layers or defaults

package/tests/DocumentManager.test.ts

@@ -337,4 +337,65 @@ 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)
+      );
+    };
+
+    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);
+    });
+  });
 });

package/tests/MimicConfig.test.ts

@@ -172,4 +172,76 @@ 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 option", () => {
+      const config = MimicConfig.make({
+        schema: TestSchema,
+        initial: { title: "My Document", count: 42 },
+      });
+
+      expect(config.initial).toEqual({ title: "My Document", count: 42 });
+    });
+
+    it("should apply defaults for omitted fields in initial state", () => {
+      const config = MimicConfig.make({
+        schema: TestSchema,
+        initial: { title: "My Document" }, // count has default of 0
+      });
+
+      expect(config.initial).toEqual({ title: "My Document", count: 0 });
+    });
+
+    it("should provide initial state 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 config.initial;
+        }).pipe(Effect.provide(testLayer))
+      );
+
+      expect(result).toEqual({ title: "From Layer", count: 100 });
+    });
+
+    it("should work with schema that has required fields without defaults", () => {
+      const SchemaWithRequired = Primitive.Struct({
+        name: Primitive.String().required(),
+        optional: Primitive.String().default("default"),
+      });
+
+      const config = MimicConfig.make({
+        schema: SchemaWithRequired,
+        initial: { name: "Required Name" },
+      });
+
+      expect(config.initial).toEqual({ name: "Required Name", optional: "default" });
+    });
+
+    it("should work with all options including initial", () => {
+      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);
+      expect(config.initial).toEqual({ title: "Full Options", count: 999 });
+    });
+  });
 });

package/tests/MimicServer.test.ts

@@ -21,84 +21,6 @@ const TestSchema = Primitive.Struct({
 // =============================================================================
 
 describe("MimicServer", () => {
-  describe("layer", () => {
-    it("should create a layer with default auth and storage", async () => {
-      const testLayer = MimicServer.layer({
-        basePath: "/mimic/test",
-        schema: TestSchema,
-      });
-
-      // Verify the layer provides the expected services
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const handler = yield* MimicServer.MimicWebSocketHandler;
-          return typeof handler === "function";
-        }).pipe(Effect.provide(testLayer))
-      );
-
-      expect(result).toBe(true);
-    });
-
-    it("should allow custom auth layer to be provided", async () => {
-      let authCalled = false;
-
-      const customAuthLayer = MimicAuthService.layer({
-        authHandler: (token) => {
-          authCalled = true;
-          return { success: true, userId: token };
-        },
-      });
-
-      const testLayer = MimicServer.layer({
-        basePath: "/mimic/test",
-        schema: TestSchema,
-      }).pipe(Layer.provideMerge(customAuthLayer));
-
-      // Verify the layer compiles with custom auth
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const handler = yield* MimicServer.MimicWebSocketHandler;
-          return typeof handler === "function";
-        }).pipe(Effect.provide(testLayer))
-      );
-
-      expect(result).toBe(true);
-    });
-
-    it("should support maxTransactionHistory option", async () => {
-      const testLayer = MimicServer.layer({
-        basePath: "/mimic/test",
-        schema: TestSchema,
-        maxTransactionHistory: 500,
-      });
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const handler = yield* MimicServer.MimicWebSocketHandler;
-          return typeof handler === "function";
-        }).pipe(Effect.provide(testLayer))
-      );
-
-      expect(result).toBe(true);
-    });
-  });
-
-  describe("handlerLayer", () => {
-    it("should create a layer that provides MimicWebSocketHandler", async () => {
-      const testLayer = MimicServer.handlerLayer({
-        schema: TestSchema,
-      });
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const handler = yield* MimicServer.MimicWebSocketHandler;
-          return typeof handler === "function";
-        }).pipe(Effect.provide(testLayer))
-      );
-
-      expect(result).toBe(true);
-    });
-  });
 
   describe("documentManagerLayer", () => {
     it("should create a layer that provides DocumentManager", async () => {
@@ -187,14 +109,6 @@ describe("MimicServer", () => {
     });
   });
 
-  describe("MimicWebSocketHandler tag", () => {
-    it("should have the correct tag identifier", () => {
-      expect(MimicServer.MimicWebSocketHandler.key).toBe(
-        "@voidhash/mimic-server-effect/MimicWebSocketHandler"
-      );
-    });
-  });
-
   describe("MimicLayerOptions", () => {
     it("should accept all optional properties", () => {
       // TypeScript compile-time check - if this compiles, the interface is correct
@@ -229,82 +143,6 @@ describe("MimicServer", () => {
       }),
     });
 
-    describe("layer", () => {
-      it("should accept presence option", async () => {
-        const testLayer = MimicServer.layer({
-          basePath: "/mimic/test",
-          schema: TestSchema,
-          presence: CursorPresence,
-        });
-
-        const result = await Effect.runPromise(
-          Effect.gen(function* () {
-            const handler = yield* MimicServer.MimicWebSocketHandler;
-            return typeof handler === "function";
-          }).pipe(Effect.provide(testLayer))
-        );
-
-        expect(result).toBe(true);
-      });
-
-      it("should work with presence and custom auth", async () => {
-        const customAuthLayer = MimicAuthService.layer({
-          authHandler: (token) => ({ success: true, userId: token }),
-        });
-
-        const testLayer = MimicServer.layer({
-          basePath: "/mimic/test",
-          schema: TestSchema,
-          presence: CursorPresence,
-        }).pipe(Layer.provideMerge(customAuthLayer));
-
-        const result = await Effect.runPromise(
-          Effect.gen(function* () {
-            const handler = yield* MimicServer.MimicWebSocketHandler;
-            return typeof handler === "function";
-          }).pipe(Effect.provide(testLayer))
-        );
-
-        expect(result).toBe(true);
-      });
-
-      it("should work with presence and maxTransactionHistory", async () => {
-        const testLayer = MimicServer.layer({
-          basePath: "/mimic/test",
-          schema: TestSchema,
-          presence: CursorPresence,
-          maxTransactionHistory: 500,
-        });
-
-        const result = await Effect.runPromise(
-          Effect.gen(function* () {
-            const handler = yield* MimicServer.MimicWebSocketHandler;
-            return typeof handler === "function";
-          }).pipe(Effect.provide(testLayer))
-        );
-
-        expect(result).toBe(true);
-      });
-    });
-
-    describe("handlerLayer", () => {
-      it("should accept presence option", async () => {
-        const testLayer = MimicServer.handlerLayer({
-          schema: TestSchema,
-          presence: CursorPresence,
-        });
-
-        const result = await Effect.runPromise(
-          Effect.gen(function* () {
-            const handler = yield* MimicServer.MimicWebSocketHandler;
-            return typeof handler === "function";
-          }).pipe(Effect.provide(testLayer))
-        );
-
-        expect(result).toBe(true);
-      });
-    });
-
     describe("documentManagerLayer", () => {
       it("should accept presence option", async () => {
         const testLayer = MimicServer.documentManagerLayer({
@@ -382,4 +220,59 @@ describe("MimicServer", () => {
       });
     });
   });
+
+  describe("initial state support", () => {
+    describe("layerHttpLayerRouter", () => {
+      it("should accept initial option", () => {
+        const routeLayer = MimicServer.layerHttpLayerRouter({
+          basePath: "/mimic/test",
+          schema: TestSchema,
+          initial: { title: "My Document", completed: true },
+        });
+
+        expect(routeLayer).toBeDefined();
+      });
+
+      it("should work with initial and all other options", () => {
+        const customAuthLayer = MimicAuthService.layer({
+          authHandler: (token) => ({ success: true, userId: token }),
+        });
+
+        const routeLayer = MimicServer.layerHttpLayerRouter({
+          basePath: "/mimic/test",
+          schema: TestSchema,
+          initial: { title: "Full Options" },
+          maxTransactionHistory: 500,
+          authLayer: customAuthLayer,
+          storageLayer: InMemoryDataStorage.layer,
+        });
+
+        expect(routeLayer).toBeDefined();
+      });
+    });
+
+    describe("MimicLayerOptions with initial", () => {
+      it("should accept initial in options", () => {
+        const options: MimicServer.MimicLayerOptions<typeof TestSchema> = {
+          schema: TestSchema,
+          basePath: "/custom/path",
+          initial: { title: "Initial State", completed: true },
+        };
+
+        expect(options.schema).toBe(TestSchema);
+        expect(options.basePath).toBe("/custom/path");
+        expect(options.initial).toEqual({ title: "Initial State", completed: true });
+      });
+
+      it("should allow omitting optional fields in initial (type safety)", () => {
+        // This test verifies that TypeScript allows omitting fields with defaults
+        const options: MimicServer.MimicLayerOptions<typeof TestSchema> = {
+          schema: TestSchema,
+          initial: { title: "Only Title" }, // completed is optional because it has a default
+        };
+
+        expect(options.initial).toEqual({ title: "Only Title" });
+      });
+    });
+  });
 });