@voidhash/mimic 0.0.1-alpha.1

package/src/Operation.ts

@@ -0,0 +1,59 @@
+
+import * as OperationPath from "./OperationPath"
+import * as OperationDefinition from "./OperationDefinition"
+import { Schema } from "effect";
+
+
+export type Operation<TKind, TPayload extends Schema.Schema.Any, TDef extends OperationDefinition.OperationDefinition<TKind, TPayload, any>> = {
+    readonly kind: TKind
+    readonly path: OperationPath.OperationPath
+    readonly payload: Schema.Schema.Type<TPayload>,
+
+} & TDef
+
+export const fromDefinition = <TKind, TPayload extends Schema.Schema.Any, TDef extends OperationDefinition.OperationDefinition<TKind, TPayload, any>>(operationPath: OperationPath.OperationPath, definition: TDef, payload: Schema.Schema.Type<TPayload>): Operation<TKind, TPayload, TDef> => {
+    return {
+        kind: definition.kind,
+        path: operationPath,
+        payload: payload,
+    } as Operation<TKind, TPayload, TDef>
+}
+
+/**
+ * Encoded representation of an Operation for network transport.
+ */
+export interface EncodedOperation {
+    readonly kind: unknown
+    readonly path: OperationPath.EncodedOperationPath
+    readonly payload: unknown
+}
+
+/**
+ * Encodes an Operation to a JSON-serializable format for network transport.
+ * @param operation - The operation to encode.
+ * @returns The encoded representation.
+ */
+export const encode = <TKind, TPayload extends Schema.Schema.Any, TDef extends OperationDefinition.OperationDefinition<TKind, TPayload, any>>(
+    operation: Operation<TKind, TPayload, TDef>
+): EncodedOperation => {
+    return {
+        kind: operation.kind,
+        path: OperationPath.encode(operation.path),
+        payload: operation.payload,
+    }
+}
+
+/**
+ * Decodes an encoded operation back to an Operation.
+ * Note: This returns a partial operation without the definition methods.
+ * The caller must have the operation definitions to fully reconstruct if needed.
+ * @param encoded - The encoded representation.
+ * @returns The decoded Operation (without definition-specific methods).
+ */
+export const decode = (encoded: EncodedOperation): Operation<unknown, Schema.Schema.Any, any> => {
+    return {
+        kind: encoded.kind,
+        path: OperationPath.decode(encoded.path),
+        payload: encoded.payload,
+    } as Operation<unknown, Schema.Schema.Any, any>
+}

package/src/OperationDefinition.ts

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+
+type Mutable<T> = T extends ReadonlyArray<infer U> ? Array<U> : { -readonly [K in keyof T]: T[K] };
+
+export interface OperationDefinition<TKind, TPayload extends Schema.Schema.Any, TTarget extends Schema.Schema.Any> {
+    readonly kind: TKind
+    readonly payload: TPayload
+    readonly target: TTarget
+}
+
+export const make = <TKind, TPayload extends Schema.Schema.Any, TTarget extends Schema.Schema.Any>(options: {
+    readonly kind: TKind
+    readonly payload: TPayload
+    readonly target: TTarget
+    readonly apply: (payload: Schema.Schema.Type<TPayload>, target: Mutable<Schema.Schema.Type<TTarget>>) => void
+}) => {
+    return {
+        kind: options.kind,
+        payload: options.payload,
+        target: options.target,
+        apply: options.apply
+    } as const;
+}

package/src/OperationPath.ts

@@ -0,0 +1,197 @@
+// export type OperationPath = string
+export type OperationPathToken = string
+
+export interface OperationPath {
+    readonly _tag: "OperationPath"
+    readonly toTokens: () => ReadonlyArray<OperationPathToken>
+    readonly concat: (other: OperationPath) => OperationPath
+    readonly append: (token: OperationPathToken) => OperationPath
+    readonly pop: () => OperationPath
+    readonly shift: () => OperationPath
+}
+
+const parseStringPath = (stringPath: string): ReadonlyArray<OperationPathToken> => {
+    return stringPath.split("/")
+}
+
+const makeStringPathFromTokens = (tokens: ReadonlyArray<OperationPathToken>): string => {
+    return tokens.join("/")
+}
+
+/**
+ * Creates a new operation path.
+ * @param stringPath - The string path to create the path from.
+ * @returns The new operation path.
+ */
+export function make(stringPath?: string): OperationPath {
+
+    const tokensInternal: ReadonlyArray<OperationPathToken> = stringPath ? parseStringPath(stringPath) : []
+
+    /**
+     * Returns the tokens of the path.
+     * @returns The tokens of the path.
+     */
+    const toTokens = () => {
+        return tokensInternal
+    }
+
+    /**
+     * Concatenates two paths.
+     * @param other - The other path to concatenate.
+     * @returns The new path.
+     */
+    const concat = (other: OperationPath): OperationPath => {
+        return make(makeStringPathFromTokens(toTokens().concat(other.toTokens())))
+    }
+
+    /**
+     * Appends a token to the path.
+     * @param token - The token to append.
+     * @returns The new path.
+     */
+    const append = (token: OperationPathToken): OperationPath => {
+        return make(makeStringPathFromTokens(toTokens().concat([token])))
+    }
+
+    /**
+     * Removes the last token from the path.
+     * @returns The new path.
+     */
+    const pop = (): OperationPath => {
+        return make(makeStringPathFromTokens(toTokens().slice(0, -1)))
+    }
+
+    /**
+     * Removes the first token from the path.
+     * @returns The new path.
+     */
+    const shift = (): OperationPath => {
+        return make(makeStringPathFromTokens(toTokens().slice(1)))
+    }
+
+    return {
+        _tag: "OperationPath",
+        toTokens,
+        concat,
+        append,
+        pop,
+        shift
+    } as const
+}
+
+/**
+ * Creates a new operation path from tokens.
+ * @param tokens - The tokens to create the path from.
+ * @returns The new operation path.
+ */
+export function fromTokens(tokens: ReadonlyArray<OperationPathToken>): OperationPath {
+    return make(makeStringPathFromTokens(tokens))
+}
+
+// =============================================================================
+// Path Utility Functions
+// =============================================================================
+
+/**
+ * Checks if two operation paths overlap (one is prefix of the other or equal).
+ */
+export const pathsOverlap = (
+  pathA: OperationPath,
+  pathB: OperationPath
+): boolean => {
+  const tokensA = pathA.toTokens().filter((t) => t !== "");
+  const tokensB = pathB.toTokens().filter((t) => t !== "");
+
+  const minLength = Math.min(tokensA.length, tokensB.length);
+
+  for (let i = 0; i < minLength; i++) {
+    if (tokensA[i] !== tokensB[i]) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Checks if pathA is a prefix of pathB (pathA is ancestor of pathB).
+ */
+export const isPrefix = (
+  pathA: OperationPath,
+  pathB: OperationPath
+): boolean => {
+  const tokensA = pathA.toTokens().filter((t) => t !== "");
+  const tokensB = pathB.toTokens().filter((t) => t !== "");
+
+  if (tokensA.length > tokensB.length) {
+    return false;
+  }
+
+  for (let i = 0; i < tokensA.length; i++) {
+    if (tokensA[i] !== tokensB[i]) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Checks if two paths are exactly equal.
+ */
+export const pathsEqual = (
+  pathA: OperationPath,
+  pathB: OperationPath
+): boolean => {
+  const tokensA = pathA.toTokens().filter((t) => t !== "");
+  const tokensB = pathB.toTokens().filter((t) => t !== "");
+
+  if (tokensA.length !== tokensB.length) {
+    return false;
+  }
+
+  for (let i = 0; i < tokensA.length; i++) {
+    if (tokensA[i] !== tokensB[i]) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Gets the relative path of pathB with respect to pathA.
+ * Assumes pathA is a prefix of pathB.
+ */
+export const getRelativePath = (
+  basePath: OperationPath,
+  fullPath: OperationPath
+): string[] => {
+  const baseTokens = basePath.toTokens().filter((t) => t !== "");
+  const fullTokens = fullPath.toTokens().filter((t) => t !== "");
+
+  return fullTokens.slice(baseTokens.length);
+};
+
+/**
+ * Encoded representation of an OperationPath for network transport.
+ */
+export type EncodedOperationPath = string;
+
+/**
+ * Encodes an OperationPath to a string for network transport.
+ * @param path - The operation path to encode.
+ * @returns The encoded string representation.
+ */
+export const encode = (path: OperationPath): EncodedOperationPath => {
+  return makeStringPathFromTokens(path.toTokens());
+};
+
+/**
+ * Decodes an encoded string back to an OperationPath.
+ * @param encoded - The encoded string representation.
+ * @returns The decoded OperationPath.
+ */
+export const decode = (encoded: EncodedOperationPath): OperationPath => {
+  return make(encoded);
+};

package/src/Presence.ts

@@ -0,0 +1,142 @@
+/**
+ * @since 0.0.1
+ * Presence module for ephemeral per-connection state.
+ * Used by both client and server for schema validation.
+ */
+import * as Schema from "effect/Schema";
+
+// =============================================================================
+// Presence Types
+// =============================================================================
+
+/**
+ * A Presence schema wrapper that holds an Effect Schema for validation.
+ * This is used by both client and server to validate presence data.
+ */
+export interface Presence<TData> {
+  readonly _tag: "Presence";
+  /** The Effect Schema used for validation */
+  readonly schema: Schema.Schema<TData>;
+  /** Branded type marker for inference */
+  readonly _Data: TData;
+}
+
+/**
+ * Options for creating a Presence instance.
+ */
+export interface PresenceOptions<TData> {
+  /** The Effect Schema defining the presence data structure */
+  readonly schema: Schema.Schema<TData>;
+}
+
+/**
+ * Infer the data type from a Presence instance.
+ */
+export type Infer<P extends Presence<any>> = P["_Data"];
+
+/**
+ * Any Presence type (for generic constraints).
+ */
+export type AnyPresence = Presence<any>;
+
+// =============================================================================
+// Presence Entry (for storage/transport)
+// =============================================================================
+
+/**
+ * A presence entry as stored/transmitted.
+ */
+export interface PresenceEntry<TData = unknown> {
+  /** The presence data */
+  readonly data: TData;
+  /** Optional user ID from authentication */
+  readonly userId?: string;
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Creates a new Presence schema wrapper.
+ *
+ * @example
+ * ```typescript
+ * import { Presence } from "@voidhash/mimic";
+ * import { Schema } from "effect";
+ *
+ * const CursorPresence = Presence.make({
+ *   schema: Schema.Struct({
+ *     name: Schema.String,
+ *     cursor: Schema.Struct({
+ *       x: Schema.Number,
+ *       y: Schema.Number,
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+export const make = <TData,>(options: PresenceOptions<TData>): Presence<TData> => ({
+  _tag: "Presence",
+  schema: options.schema,
+  _Data: undefined as unknown as TData,
+});
+
+// =============================================================================
+// Validation Functions
+// =============================================================================
+
+/**
+ * Validates unknown data against a Presence schema.
+ * Throws a ParseError if validation fails.
+ *
+ * @param presence - The Presence instance with the schema
+ * @param data - Unknown data to validate
+ * @returns The validated and typed data
+ * @throws ParseError if validation fails
+ */
+export const validate = <TData,>(
+  presence: Presence<TData>,
+  data: unknown
+): TData => {
+  return Schema.decodeUnknownSync(presence.schema)(data);
+};
+
+/**
+ * Safely validates unknown data against a Presence schema.
+ * Returns undefined if validation fails instead of throwing.
+ *
+ * @param presence - The Presence instance with the schema
+ * @param data - Unknown data to validate
+ * @returns The validated data or undefined if invalid
+ */
+export const validateSafe = <TData,>(
+  presence: Presence<TData>,
+  data: unknown
+): TData | undefined => {
+  try {
+    return Schema.decodeUnknownSync(presence.schema)(data);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Checks if unknown data is valid according to a Presence schema.
+ *
+ * @param presence - The Presence instance with the schema
+ * @param data - Unknown data to check
+ * @returns true if valid, false otherwise
+ */
+export const isValid = <TData,>(
+  presence: Presence<TData>,
+  data: unknown
+): data is TData => {
+  try {
+    Schema.decodeUnknownSync(presence.schema)(data);
+    return true;
+  } catch {
+    return false;
+  }
+};
+

package/src/Primitive.ts

@@ -0,0 +1,32 @@
+
+// =============================================================================
+// Re-export all primitives from separate files
+// =============================================================================
+
+export * from "./primitives/shared";
+
+// String Primitive
+export * from "./primitives/String";
+// Struct Primitive
+export * from "./primitives/Struct";
+
+// Boolean Primitive
+export * from "./primitives/Boolean";
+
+// Number Primitive
+export * from "./primitives/Number";
+// Literal Primitive
+export * from "./primitives/Literal";
+
+// Array Primitive
+export * from "./primitives/Array";
+// Lazy Primitive
+export * from "./primitives/Lazy";
+
+// Union Primitive
+export * from "./primitives/Union";
+
+// TreeNode Primitive
+export * from "./primitives/TreeNode";
+// Tree Primitive
+export * from "./primitives/Tree";

package/src/Proxy.ts

@@ -0,0 +1,8 @@
+import * as ProxyEnvironment from "./ProxyEnvironment";
+import * as OperationPath from "./OperationPath";
+
+export type Proxy<T> = T
+
+export const factory = <T,>(fn: (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath) => Proxy<T>) => {
+    return (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath) => fn(env, operationPath)
+}

package/src/ProxyEnvironment.ts

@@ -0,0 +1,52 @@
+import * as Operation from "./Operation";
+import * as OperationPath from "./OperationPath";
+
+export type ProxyEnvironment = {
+  /** Adds an operation to be collected/applied */
+  readonly addOperation: (operation: Operation.Operation<any, any, any>) => void;
+  /** Gets the current state at the given path */
+  readonly getState: (path: OperationPath.OperationPath) => unknown;
+  /** Generates a unique ID (UUID) for array elements */
+  readonly generateId: () => string;
+};
+
+export interface ProxyEnvironmentOptions {
+  /** Callback when an operation is added */
+  readonly onOperation: (operation: Operation.Operation<any, any, any>) => void;
+  /** Function to retrieve current state at a path (defaults to returning undefined) */
+  readonly getState?: (path: OperationPath.OperationPath) => unknown;
+  /** Optional: Custom ID generator (defaults to crypto.randomUUID) */
+  readonly generateId?: () => string;
+}
+
+/** Default UUID generator using crypto.randomUUID */
+const defaultGenerateId = (): string => {
+  return crypto.randomUUID();
+};
+
+/** Default state getter that always returns undefined */
+const defaultGetState = (_path: OperationPath.OperationPath): unknown => {
+  return undefined;
+};
+
+/**
+ * Creates a ProxyEnvironment.
+ * @param optionsOrCallback - Either an options object or a simple callback for operations
+ */
+export const make = (
+  optionsOrCallback: ProxyEnvironmentOptions | ((operation: Operation.Operation<any, any, any>) => void)
+): ProxyEnvironment => {
+  // Support both old callback style and new options object
+  const options: ProxyEnvironmentOptions =
+    typeof optionsOrCallback === "function"
+      ? { onOperation: optionsOrCallback }
+      : optionsOrCallback;
+
+  return {
+    addOperation: (operation: Operation.Operation<any, any, any>) => {
+      options.onOperation(operation);
+    },
+    getState: options.getState ?? defaultGetState,
+    generateId: options.generateId ?? defaultGenerateId,
+  };
+};

package/src/Transaction.ts

@@ -0,0 +1,72 @@
+import * as Operation from "./Operation";
+
+/**
+ * A Transaction represents a group of operations that were applied atomically.
+ */
+export interface Transaction {
+  /** Unique identifier for this transaction */
+  readonly id: string;
+  /** Operations contained in this transaction */
+  readonly ops: ReadonlyArray<Operation.Operation<any, any, any>>;
+  /** Timestamp when the transaction was created */
+  readonly timestamp: number;
+}
+
+/**
+ * Creates a new Transaction with the given operations.
+ */
+export const make = (ops: ReadonlyArray<Operation.Operation<any, any, any>>): Transaction => ({
+  id: crypto.randomUUID(),
+  ops,
+  timestamp: Date.now(),
+});
+
+/**
+ * Creates an empty Transaction.
+ */
+export const empty = (): Transaction => make([]);
+
+/**
+ * Checks if a transaction is empty (has no operations).
+ */
+export const isEmpty = (tx: Transaction): boolean => tx.ops.length === 0;
+
+/**
+ * Merges multiple transactions into one.
+ */
+export const merge = (txs: ReadonlyArray<Transaction>): Transaction => {
+  const allOps = txs.flatMap(tx => tx.ops);
+  return make(allOps);
+};
+
+
+/**
+ * Encoded representation of a Transaction for network transport.
+ */
+export interface EncodedTransaction {
+  readonly id: string;
+  readonly ops: ReadonlyArray<Operation.EncodedOperation>;
+  readonly timestamp: number;
+}
+
+/**
+ * Encodes a Transaction to a JSON-serializable format for network transport.
+ * @param transaction - The transaction to encode.
+ * @returns The encoded representation.
+ */
+export const encode = (transaction: Transaction): EncodedTransaction => ({
+  id: transaction.id,
+  ops: transaction.ops.map(Operation.encode),
+  timestamp: transaction.timestamp,
+});
+
+/**
+ * Decodes an encoded transaction back to a Transaction.
+ * @param encoded - The encoded representation.
+ * @returns The decoded Transaction.
+ */
+export const decode = (encoded: EncodedTransaction): Transaction => ({
+  id: encoded.id,
+  ops: encoded.ops.map(Operation.decode),
+  timestamp: encoded.timestamp,
+});

package/src/Transform.ts

@@ -0,0 +1,13 @@
+import type * as Operation from "./Operation";
+
+// =============================================================================
+// Transform Result Types
+// =============================================================================
+
+/**
+ * Result of transforming an operation against another operation.
+ */
+export type TransformResult =
+  | { type: "transformed"; operation: Operation.Operation<any, any, any> }
+  | { type: "noop" } // Operation becomes a no-op (already superseded)
+  | { type: "conflict"; reason: string };