@voidhash/mimic 0.0.1-alpha.1

package/src/primitives/Lazy.ts

@@ -0,0 +1,89 @@
+import { Effect, Schema } from "effect";
+import * as OperationDefinition from "../OperationDefinition";
+import * as Operation from "../Operation";
+import * as OperationPath from "../OperationPath";
+import * as ProxyEnvironment from "../ProxyEnvironment";
+import * as Transform from "../Transform";
+import type { Primitive, PrimitiveInternal, AnyPrimitive, InferState, InferProxy, InferSnapshot } from "../Primitive";
+import { ValidationError } from "../Primitive";
+import { runValidators } from "./shared";
+
+
+/**
+ * Type to infer state from a lazy thunk
+ */
+export type InferLazyState<T extends () => AnyPrimitive> = InferState<ReturnType<T>>;
+
+/**
+ * Type to infer proxy from a lazy thunk
+ */
+export type InferLazyProxy<T extends () => AnyPrimitive> = InferProxy<ReturnType<T>>;
+
+/**
+ * Type to infer snapshot from a lazy thunk
+ */
+export type InferLazySnapshot<T extends () => AnyPrimitive> = InferSnapshot<ReturnType<T>>;
+
+export class LazyPrimitive<TThunk extends () => AnyPrimitive>
+  implements Primitive<InferLazyState<TThunk>, InferLazyProxy<TThunk>>
+{
+  readonly _tag = "LazyPrimitive" as const;
+  readonly _State!: InferLazyState<TThunk>;
+  readonly _Proxy!: InferLazyProxy<TThunk>;
+
+  private readonly _thunk: TThunk;
+  private _resolved: ReturnType<TThunk> | undefined;
+
+  constructor(thunk: TThunk) {
+    this._thunk = thunk;
+  }
+
+  /** Resolve and cache the lazy primitive */
+  private _resolve(): ReturnType<TThunk> {
+    if (this._resolved === undefined) {
+      this._resolved = this._thunk() as ReturnType<TThunk>;
+    }
+    return this._resolved;
+  }
+
+  /** Mark this lazy primitive as required (delegates to resolved) */
+  required(): LazyPrimitive<TThunk> {
+    // Note: For lazy, we can't easily propagate required to the resolved primitive
+    // without resolving it first. This is a limitation.
+    return this;
+  }
+
+  readonly _internal: PrimitiveInternal<InferLazyState<TThunk>, InferLazyProxy<TThunk>> = {
+    createProxy: (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath): InferLazyProxy<TThunk> => {
+      const resolved = this._resolve();
+      return resolved._internal.createProxy(env, operationPath) as InferLazyProxy<TThunk>;
+    },
+
+    applyOperation: (
+      state: InferLazyState<TThunk> | undefined,
+      operation: Operation.Operation<any, any, any>
+    ): InferLazyState<TThunk> => {
+      const resolved = this._resolve();
+      return resolved._internal.applyOperation(state, operation) as InferLazyState<TThunk>;
+    },
+
+    getInitialState: (): InferLazyState<TThunk> | undefined => {
+      const resolved = this._resolve();
+      return resolved._internal.getInitialState() as InferLazyState<TThunk> | undefined;
+    },
+
+    transformOperation: (
+      clientOp: Operation.Operation<any, any, any>,
+      serverOp: Operation.Operation<any, any, any>
+    ): Transform.TransformResult => {
+      // Delegate to resolved primitive
+      const resolved = this._resolve();
+      return resolved._internal.transformOperation(clientOp, serverOp);
+    },
+  };
+}
+
+/** Creates a new LazyPrimitive with the given thunk */
+export const Lazy = <TThunk extends () => AnyPrimitive>(thunk: TThunk): LazyPrimitive<TThunk> =>
+  new LazyPrimitive(thunk);
+

package/src/primitives/Literal.ts

@@ -0,0 +1,128 @@
+import { Schema } from "effect";
+import * as OperationDefinition from "../OperationDefinition";
+import * as Operation from "../Operation";
+import * as OperationPath from "../OperationPath";
+import * as ProxyEnvironment from "../ProxyEnvironment";
+import * as Transform from "../Transform";
+import type { Primitive, PrimitiveInternal, MaybeUndefined, AnyPrimitive, Validator } from "../Primitive";
+import { ValidationError } from "../Primitive";
+import { runValidators, isCompatibleOperation } from "./shared";
+
+
+/** Valid literal types */
+export type LiteralValue = string | number | boolean | null;
+
+export interface LiteralProxy<T extends LiteralValue, TDefined extends boolean = false> {
+  /** Gets the current literal value */
+  get(): MaybeUndefined<T, TDefined>;
+  /** Sets the literal value (must match the exact literal type) */
+  set(value: T): void;
+  /** Returns a readonly snapshot of the literal value for rendering */
+  toSnapshot(): MaybeUndefined<T, TDefined>;
+}
+
+interface LiteralPrimitiveSchema<T extends LiteralValue> {
+  readonly required: boolean;
+  readonly defaultValue: T | undefined;
+  readonly literal: T;
+}
+
+export class LiteralPrimitive<T extends LiteralValue, TDefined extends boolean = false> implements Primitive<T, LiteralProxy<T, TDefined>> {
+  readonly _tag = "LiteralPrimitive" as const;
+  readonly _State!: T;
+  readonly _Proxy!: LiteralProxy<T, TDefined>;
+
+  private readonly _schema: LiteralPrimitiveSchema<T>;
+
+  private readonly _opDefinitions = {
+    set: OperationDefinition.make({
+      kind: "literal.set" as const,
+      payload: Schema.Unknown,
+      target: Schema.Unknown,
+      apply: (payload) => payload,
+    }),
+  };
+
+  constructor(schema: LiteralPrimitiveSchema<T>) {
+    this._schema = schema;
+  }
+
+  /** Mark this literal as required */
+  required(): LiteralPrimitive<T, true> {
+    return new LiteralPrimitive({
+      ...this._schema,
+      required: true,
+    });
+  }
+
+  /** Set a default value for this literal */
+  default(defaultValue: T): LiteralPrimitive<T, true> {
+    return new LiteralPrimitive({
+      ...this._schema,
+      defaultValue,
+    });
+  }
+
+  /** Get the literal value this primitive represents */
+  get literal(): T {
+    return this._schema.literal;
+  }
+
+  readonly _internal: PrimitiveInternal<T, LiteralProxy<T, TDefined>> = {
+    createProxy: (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath): LiteralProxy<T, TDefined> => {
+      const defaultValue = this._schema.defaultValue;
+      return {
+        get: (): MaybeUndefined<T, TDefined> => {
+          const state = env.getState(operationPath) as T | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<T, TDefined>;
+        },
+        set: (value: T) => {
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, value)
+          );
+        },
+        toSnapshot: (): MaybeUndefined<T, TDefined> => {
+          const state = env.getState(operationPath) as T | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<T, TDefined>;
+        },
+      };
+    },
+
+    applyOperation: (state: T | undefined, operation: Operation.Operation<any, any, any>): T => {
+      if (operation.kind !== "literal.set") {
+        throw new ValidationError(`LiteralPrimitive cannot apply operation of kind: ${operation.kind}`);
+      }
+
+      const payload = operation.payload;
+      if (payload !== this._schema.literal) {
+        throw new ValidationError(
+          `LiteralPrimitive.set requires the exact literal value "${globalThis.String(this._schema.literal)}", got: "${globalThis.String(payload)}"`
+        );
+      }
+
+      return payload as T;
+    },
+
+    getInitialState: (): T | undefined => {
+      return this._schema.defaultValue;
+    },
+
+    transformOperation: (
+      clientOp: Operation.Operation<any, any, any>,
+      serverOp: Operation.Operation<any, any, any>
+    ): Transform.TransformResult => {
+      // If paths don't overlap, no transformation needed
+      if (!OperationPath.pathsOverlap(clientOp.path, serverOp.path)) {
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // For same path, client wins (last-write-wins)
+      return { type: "transformed", operation: clientOp };
+    },
+  };
+}
+
+/** Creates a new LiteralPrimitive with the given literal value */
+export const Literal = <T extends LiteralValue>(literal: T): LiteralPrimitive<T, false> =>
+  new LiteralPrimitive({ required: false, defaultValue: undefined, literal });
+

package/src/primitives/Number.ts

@@ -0,0 +1,169 @@
+import { Schema } from "effect";
+import * as OperationDefinition from "../OperationDefinition";
+import * as Operation from "../Operation";
+import * as OperationPath from "../OperationPath";
+import * as ProxyEnvironment from "../ProxyEnvironment";
+import * as Transform from "../Transform";
+import type { Primitive, PrimitiveInternal, MaybeUndefined, AnyPrimitive, Validator } from "../Primitive";
+import { ValidationError } from "../Primitive";
+import { runValidators, isCompatibleOperation } from "./shared";
+
+
+export interface NumberProxy<TDefined extends boolean = false> {
+  /** Gets the current number value */
+  get(): MaybeUndefined<number, TDefined>;
+  /** Sets the number value, generating a number.set operation */
+  set(value: number): void;
+  /** Returns a readonly snapshot of the number value for rendering */
+  toSnapshot(): MaybeUndefined<number, TDefined>;
+}
+
+interface NumberPrimitiveSchema {
+  readonly required: boolean;
+  readonly defaultValue: number | undefined;
+  readonly validators: readonly Validator<number>[];
+}
+
+export class NumberPrimitive<TDefined extends boolean = false> implements Primitive<number, NumberProxy<TDefined>> {
+  readonly _tag = "NumberPrimitive" as const;
+  readonly _State!: number;
+  readonly _Proxy!: NumberProxy<TDefined>;
+
+  private readonly _schema: NumberPrimitiveSchema;
+
+  private readonly _opDefinitions = {
+    set: OperationDefinition.make({
+      kind: "number.set" as const,
+      payload: Schema.Number,
+      target: Schema.Number,
+      apply: (payload) => payload,
+    }),
+  };
+
+  constructor(schema: NumberPrimitiveSchema) {
+    this._schema = schema;
+  }
+
+  /** Mark this number as required */
+  required(): NumberPrimitive<true> {
+    return new NumberPrimitive({
+      ...this._schema,
+      required: true,
+    });
+  }
+
+  /** Set a default value for this number */
+  default(defaultValue: number): NumberPrimitive<true> {
+    return new NumberPrimitive({
+      ...this._schema,
+      defaultValue,
+    });
+  }
+
+  /** Add a custom validation rule */
+  refine(fn: (value: number) => boolean, message: string): NumberPrimitive<TDefined> {
+    return new NumberPrimitive({
+      ...this._schema,
+      validators: [...this._schema.validators, { validate: fn, message }],
+    });
+  }
+
+  /** Minimum value (inclusive) */
+  min(value: number): NumberPrimitive<TDefined> {
+    return this.refine(
+      (v) => v >= value,
+      `Number must be at least ${value}`
+    );
+  }
+
+  /** Maximum value (inclusive) */
+  max(value: number): NumberPrimitive<TDefined> {
+    return this.refine(
+      (v) => v <= value,
+      `Number must be at most ${value}`
+    );
+  }
+
+  /** Must be positive (> 0) */
+  positive(): NumberPrimitive<TDefined> {
+    return this.refine(
+      (v) => v > 0,
+      "Number must be positive"
+    );
+  }
+
+  /** Must be negative (< 0) */
+  negative(): NumberPrimitive<TDefined> {
+    return this.refine(
+      (v) => v < 0,
+      "Number must be negative"
+    );
+  }
+
+  /** Must be an integer */
+  int(): NumberPrimitive<TDefined> {
+    return this.refine(
+      (v) => globalThis.Number.isInteger(v),
+      "Number must be an integer"
+    );
+  }
+
+  readonly _internal: PrimitiveInternal<number, NumberProxy<TDefined>> = {
+    createProxy: (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath): NumberProxy<TDefined> => {
+      const defaultValue = this._schema.defaultValue;
+      return {
+        get: (): MaybeUndefined<number, TDefined> => {
+          const state = env.getState(operationPath) as number | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<number, TDefined>;
+        },
+        set: (value: number) => {
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, value)
+          );
+        },
+        toSnapshot: (): MaybeUndefined<number, TDefined> => {
+          const state = env.getState(operationPath) as number | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<number, TDefined>;
+        },
+      };
+    },
+
+    applyOperation: (state: number | undefined, operation: Operation.Operation<any, any, any>): number => {
+      if (operation.kind !== "number.set") {
+        throw new ValidationError(`NumberPrimitive cannot apply operation of kind: ${operation.kind}`);
+      }
+
+      const payload = operation.payload;
+      if (typeof payload !== "number") {
+        throw new ValidationError(`NumberPrimitive.set requires a number payload, got: ${typeof payload}`);
+      }
+
+      // Run validators
+      runValidators(payload, this._schema.validators);
+
+      return payload;
+    },
+
+    getInitialState: (): number | undefined => {
+      return this._schema.defaultValue;
+    },
+
+    transformOperation: (
+      clientOp: Operation.Operation<any, any, any>,
+      serverOp: Operation.Operation<any, any, any>
+    ): Transform.TransformResult => {
+      // If paths don't overlap, no transformation needed
+      if (!OperationPath.pathsOverlap(clientOp.path, serverOp.path)) {
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // For same path, client wins (last-write-wins)
+      return { type: "transformed", operation: clientOp };
+    },
+  };
+}
+
+/** Creates a new NumberPrimitive */
+export const Number = (): NumberPrimitive<false> =>
+  new NumberPrimitive({ required: false, defaultValue: undefined, validators: [] });
+

package/src/primitives/String.ts

@@ -0,0 +1,189 @@
+import { Schema } from "effect";
+import * as OperationDefinition from "../OperationDefinition";
+import * as Operation from "../Operation";
+import * as OperationPath from "../OperationPath";
+import * as ProxyEnvironment from "../ProxyEnvironment";
+import * as Transform from "../Transform";
+import type { Primitive, PrimitiveInternal, MaybeUndefined, Validator } from "./shared";
+import { runValidators, isCompatibleOperation, ValidationError } from "./shared";
+
+// =============================================================================
+// String Primitive
+// =============================================================================
+
+export interface StringProxy<TDefined extends boolean = false> {
+  /** Gets the current string value */
+  get(): MaybeUndefined<string, TDefined>;
+  /** Sets the string value, generating a string.set operation */
+  set(value: string): void;
+  /** Returns a readonly snapshot of the string value for rendering */
+  toSnapshot(): MaybeUndefined<string, TDefined>;
+}
+
+interface StringPrimitiveSchema {
+  readonly required: boolean;
+  readonly defaultValue: string | undefined;
+  readonly validators: readonly Validator<string>[];
+}
+
+export class StringPrimitive<TDefined extends boolean = false> implements Primitive<string, StringProxy<TDefined>> {
+  readonly _tag = "StringPrimitive" as const;
+  readonly _State!: string;
+  readonly _Proxy!: StringProxy<TDefined>;
+
+  private readonly _schema: StringPrimitiveSchema;
+
+  private readonly _opDefinitions = {
+    set: OperationDefinition.make({
+      kind: "string.set" as const,
+      payload: Schema.String,
+      target: Schema.String,
+      apply: (payload) => payload,
+    }),
+  };
+
+  constructor(schema: StringPrimitiveSchema) {
+    this._schema = schema;
+  }
+
+  /** Mark this string as required */
+  required(): StringPrimitive<true> {
+    return new StringPrimitive({
+      ...this._schema,
+      required: true,
+    });
+  }
+
+  /** Set a default value for this string */
+  default(defaultValue: string): StringPrimitive<true> {
+    return new StringPrimitive({
+      ...this._schema,
+      defaultValue,
+    });
+  }
+
+  /** Add a custom validation rule */
+  refine(fn: (value: string) => boolean, message: string): StringPrimitive<TDefined> {
+    return new StringPrimitive({
+      ...this._schema,
+      validators: [...this._schema.validators, { validate: fn, message }],
+    });
+  }
+
+  /** Minimum string length */
+  min(length: number): StringPrimitive<TDefined> {
+    return this.refine(
+      (v) => v.length >= length,
+      `String must be at least ${length} characters`
+    );
+  }
+
+  /** Maximum string length */
+  max(length: number): StringPrimitive<TDefined> {
+    return this.refine(
+      (v) => v.length <= length,
+      `String must be at most ${length} characters`
+    );
+  }
+
+  /** Exact string length */
+  length(exact: number): StringPrimitive<TDefined> {
+    return this.refine(
+      (v) => v.length === exact,
+      `String must be exactly ${exact} characters`
+    );
+  }
+
+  /** Match a regex pattern */
+  regex(pattern: RegExp, message?: string): StringPrimitive<TDefined> {
+    return this.refine(
+      (v) => pattern.test(v),
+      message ?? `String must match pattern ${pattern}`
+    );
+  }
+
+  /** Validate as email format */
+  email(): StringPrimitive<TDefined> {
+    // Simple email regex - covers most common cases
+    const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return this.refine(
+      (v) => emailPattern.test(v),
+      "Invalid email format"
+    );
+  }
+
+  /** Validate as URL format */
+  url(): StringPrimitive<TDefined> {
+    return this.refine(
+      (v) => {
+        try {
+          new URL(v);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      "Invalid URL format"
+    );
+  }
+
+  readonly _internal: PrimitiveInternal<string, StringProxy<TDefined>> = {
+    createProxy: (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath): StringProxy<TDefined> => {
+      const defaultValue = this._schema.defaultValue;
+      return {
+        get: (): MaybeUndefined<string, TDefined> => {
+          const state = env.getState(operationPath) as string | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<string, TDefined>;
+        },
+        set: (value: string) => {
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, value)
+          );
+        },
+        toSnapshot: (): MaybeUndefined<string, TDefined> => {
+          const state = env.getState(operationPath) as string | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<string, TDefined>;
+        },
+      };
+    },
+
+    applyOperation: (state: string | undefined, operation: Operation.Operation<any, any, any>): string => {
+      if (!isCompatibleOperation(operation, this._opDefinitions)) {
+        throw new ValidationError(`StringPrimitive cannot apply operation of kind: ${operation.kind}`);
+      }
+
+      const payload = operation.payload;
+      if (typeof payload !== "string") {
+        throw new ValidationError(`StringPrimitive.set requires a string payload, got: ${typeof payload}`);
+      }
+
+      // Run validators
+      runValidators(payload, this._schema.validators);
+
+      return payload;
+    },
+
+    getInitialState: (): string | undefined => {
+      return this._schema.defaultValue;
+    },
+
+    transformOperation: (
+      clientOp: Operation.Operation<any, any, any>,
+      serverOp: Operation.Operation<any, any, any>
+    ): Transform.TransformResult => {
+      // If paths don't overlap, no transformation needed
+      if (!OperationPath.pathsOverlap(clientOp.path, serverOp.path)) {
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // For same path, client wins (last-write-wins)
+      // Client operation proceeds as-is
+      return { type: "transformed", operation: clientOp };
+    },
+  };
+}
+
+/** Creates a new StringPrimitive */
+export const String = (): StringPrimitive<false> =>
+  new StringPrimitive({ required: false, defaultValue: undefined, validators: [] });
+