@voidhash/mimic 0.0.1-alpha.4 → 0.0.1-alpha.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidhash/mimic",
-  "version": "0.0.1-alpha.4",
+  "version": "0.0.1-alpha.6",
   "type": "module",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
     "typescript": "5.8.3",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4",
-    "@voidhash/tsconfig": "0.0.1-alpha.4"
+    "@voidhash/tsconfig": "0.0.1-alpha.6"
   },
   "peerDependencies": {
     "effect": "^3.19.12"

package/src/client/ClientDocument.ts

@@ -43,7 +43,7 @@ type InitState =
 /**
  * Listener for presence changes.
  */
-export interface PresenceListener<TData> {
+export interface PresenceListener<_TData> {
   /** Called when any presence changes (self or others) */
   readonly onPresenceChange?: () => void;
 }

package/src/client/errors.ts

@@ -19,7 +19,7 @@ export class MimicClientError extends Error {
  * Error thrown when a transaction is rejected by the server.
  */
 export class TransactionRejectedError extends MimicClientError {
-  readonly _tag = "TransactionRejectedError";
+  override readonly _tag = "TransactionRejectedError";
   readonly transaction: Transaction.Transaction;
   readonly reason: string;
 
@@ -35,7 +35,7 @@ export class TransactionRejectedError extends MimicClientError {
  * Error thrown when the transport is not connected.
  */
 export class NotConnectedError extends MimicClientError {
-  readonly _tag = "NotConnectedError";
+  override readonly _tag = "NotConnectedError";
   constructor() {
     super("Transport is not connected");
     this.name = "NotConnectedError";
@@ -46,8 +46,8 @@ export class NotConnectedError extends MimicClientError {
  * Error thrown when connection to the server fails.
  */
 export class ConnectionError extends MimicClientError {
-  readonly _tag = "ConnectionError";
-  readonly cause?: Error;
+  override readonly _tag = "ConnectionError";
+  override readonly cause?: Error;
 
   constructor(message: string, cause?: Error) {
     super(message);
@@ -60,7 +60,7 @@ export class ConnectionError extends MimicClientError {
  * Error thrown when state drift is detected and cannot be recovered.
  */
 export class StateDriftError extends MimicClientError {
-  readonly _tag = "StateDriftError";
+  override readonly _tag = "StateDriftError";
   readonly expectedVersion: number;
   readonly receivedVersion: number;
 
@@ -78,7 +78,7 @@ export class StateDriftError extends MimicClientError {
  * Error thrown when a pending transaction times out waiting for confirmation.
  */
 export class TransactionTimeoutError extends MimicClientError {
-  readonly _tag = "TransactionTimeoutError";
+  override readonly _tag = "TransactionTimeoutError";
   readonly transaction: Transaction.Transaction;
   readonly timeoutMs: number;
 
@@ -96,7 +96,7 @@ export class TransactionTimeoutError extends MimicClientError {
  * Error thrown when rebasing operations fails.
  */
 export class RebaseError extends MimicClientError {
-  readonly _tag = "RebaseError";
+  override readonly _tag = "RebaseError";
   readonly transactionId: string;
 
   constructor(transactionId: string, message: string) {
@@ -110,7 +110,7 @@ export class RebaseError extends MimicClientError {
  * Error thrown when the client document is in an invalid state.
  */
 export class InvalidStateError extends MimicClientError {
-  readonly _tag = "InvalidStateError";
+  override readonly _tag = "InvalidStateError";
   constructor(message: string) {
     super(message);
     this.name = "InvalidStateError";
@@ -121,7 +121,7 @@ export class InvalidStateError extends MimicClientError {
  * Error thrown when WebSocket connection or communication fails.
  */
 export class WebSocketError extends MimicClientError {
-  readonly _tag = "WebSocketError";
+  override readonly _tag = "WebSocketError";
   readonly code?: number;
   readonly reason?: string;
 
@@ -137,7 +137,7 @@ export class WebSocketError extends MimicClientError {
  * Error thrown when authentication fails.
  */
 export class AuthenticationError extends MimicClientError {
-  readonly _tag = "AuthenticationError";
+  override readonly _tag = "AuthenticationError";
   constructor(message: string) {
     super(message);
     this.name = "AuthenticationError";

package/src/primitives/Boolean.ts

@@ -87,7 +87,7 @@ export class BooleanPrimitive<TDefined extends boolean = false> implements Primi
       };
     },
 
-    applyOperation: (state: boolean | undefined, operation: Operation.Operation<any, any, any>): boolean => {
+    applyOperation: (_state: boolean | undefined, operation: Operation.Operation<any, any, any>): boolean => {
       if (operation.kind !== "boolean.set") {
         throw new ValidationError(`BooleanPrimitive cannot apply operation of kind: ${operation.kind}`);
       }

package/src/primitives/Literal.ts

@@ -88,7 +88,7 @@ export class LiteralPrimitive<T extends LiteralValue, TDefined extends boolean =
       };
     },
 
-    applyOperation: (state: T | undefined, operation: Operation.Operation<any, any, any>): T => {
+    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}`);
       }

package/src/primitives/Number.ts

@@ -128,7 +128,7 @@ export class NumberPrimitive<TDefined extends boolean = false> implements Primit
       };
     },
 
-    applyOperation: (state: number | undefined, operation: Operation.Operation<any, any, any>): number => {
+    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}`);
       }

package/src/primitives/String.ts

@@ -147,7 +147,7 @@ export class StringPrimitive<TDefined extends boolean = false> implements Primit
       };
     },
 
-    applyOperation: (state: string | undefined, operation: Operation.Operation<any, any, any>): string => {
+    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}`);
       }

package/src/primitives/Struct.ts

@@ -149,7 +149,7 @@ export class StructPrimitive<TFields extends Record<string, AnyPrimitive>, TDefi
 
       // Use a JavaScript Proxy to intercept field access
       return new globalThis.Proxy(base as StructProxy<TFields, TDefined>, {
-        get: (target, prop, receiver) => {
+        get: (target, prop, _receiver) => {
           // Return base methods (get, set, toSnapshot)
           if (prop === "get") {
             return target.get;
@@ -175,7 +175,7 @@ export class StructPrimitive<TFields extends Record<string, AnyPrimitive>, TDefi
 
           return undefined;
         },
-        has: (target, prop) => {
+        has: (_target, prop) => {
           if (prop === "get" || prop === "set" || prop === "toSnapshot") return true;
           if (typeof prop === "string" && prop in fields) return true;
           return false;

package/src/primitives/Tree.ts

@@ -37,7 +37,7 @@ export interface TypedTreeNodeState<TNode extends AnyTreeNodePrimitive> {
 /**
  * The state type for trees - a flat array of nodes
  */
-export type TreeState<TRoot extends AnyTreeNodePrimitive> = readonly TreeNodeState[];
+export type TreeState<_TRoot extends AnyTreeNodePrimitive> = readonly TreeNodeState[];
 
 /**
  * Helper to get children sorted by position
@@ -122,7 +122,7 @@ export interface TypedNodeProxy<TNode extends AnyTreeNodePrimitive> {
 /**
  * Node proxy with type narrowing capabilities
  */
-export interface TreeNodeProxyBase<TRoot extends AnyTreeNodePrimitive> {
+export interface TreeNodeProxyBase<_TRoot extends AnyTreeNodePrimitive> {
   /** The node ID */
   readonly id: string;
   /** The node type (string) */

package/src/primitives/TreeNode.ts

@@ -1,23 +1,64 @@
-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 { AnyPrimitive, InferState } from "../Primitive";
+import type { InferState } from "../Primitive";
 import { StructPrimitive } from "./Struct";
 
+/**
+ * Symbol used to identify the Self placeholder
+ */
+const TreeNodeSelfSymbol = Symbol.for("TreeNode.Self");
 
 /**
- * Any TreeNodePrimitive type - used for generic constraints.
+ * Branded type for TreeNodeSelf - distinguishable at compile time
+ */
+declare const SelfBrand: unique symbol;
+export interface TreeNodeSelfType {
+  readonly _tag: "TreeNodeSelf";
+  readonly _brand: typeof SelfBrand;
+}
+
+/**
+ * Special placeholder for self-referential tree nodes.
+ * Use this in the children array when a node type can contain itself.
+ * 
+ * @example
+ * ```typescript
+ * const FolderNode = TreeNode("folder", {
+ *   data: Struct({ name: String() }),
+ *   children: [TreeNodeSelf], // Folder can contain other folders
+ * });
+ * ```
+ */
+export const TreeNodeSelf: TreeNodeSelfType = { _tag: "TreeNodeSelf", _symbol: TreeNodeSelfSymbol } as unknown as TreeNodeSelfType;
+
+/**
+ * Check if a value is the Self placeholder
  */
-export type AnyTreeNodePrimitive = TreeNodePrimitive<string, StructPrimitive<any>, readonly AnyTreeNodePrimitive[] | (() => readonly AnyTreeNodePrimitive[])>;
+const isSelf = (value: unknown): boolean => {
+  return typeof value === "object" && value !== null && "_symbol" in value && (value as any)._symbol === TreeNodeSelfSymbol;
+};
 
 /**
- * Resolves children type - handles both array and lazy thunk
+ * Type utility to resolve Self placeholders to the actual node type
+ */
+type ResolveSelf<T, TSelf extends AnyTreeNodePrimitive> = 
+  T extends TreeNodeSelfType ? TSelf : T;
+
+/**
+ * Type utility to resolve all children in a tuple, replacing Self with the node type
+ */
+type ResolveChildrenUnion<TChildren, TSelf extends AnyTreeNodePrimitive> = 
+  TChildren extends readonly (infer U)[] 
+    ? ResolveSelf<U, TSelf> 
+    : never;
+
+/**
+ * The type for children - either a direct array or a lazy function (for self-referential nodes).
+ */
+export type TreeNodeChildrenInput = readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[] | (() => readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]);
+
+/**
+ * Any TreeNodePrimitive type - used for generic constraints.
  */
-export type ResolveChildren<TChildren extends readonly AnyTreeNodePrimitive[] | (() => readonly AnyTreeNodePrimitive[])> =
-  TChildren extends () => readonly AnyTreeNodePrimitive[] ? ReturnType<TChildren> : TChildren;
+export type AnyTreeNodePrimitive = TreeNodePrimitive<string, StructPrimitive<any>, any>;
 
 /**
  * Infer the data state type from a TreeNodePrimitive
@@ -34,18 +75,18 @@ export type InferTreeNodeType<T extends AnyTreeNodePrimitive> =
 /**
  * Infer the allowed children from a TreeNodePrimitive
  */
-export type InferTreeNodeChildren<T extends AnyTreeNodePrimitive> =
-  T extends TreeNodePrimitive<any, any, infer TChildren> ? ResolveChildren<TChildren>[number] : never;
+export type InferTreeNodeChildren<T> = 
+  T extends TreeNodePrimitive<any, any, infer TChildren> ? TChildren : never;
 
 /**
  * Configuration for a TreeNode primitive
  */
 export interface TreeNodeConfig<
   TData extends StructPrimitive<any>,
-  TChildren extends readonly AnyTreeNodePrimitive[] | (() => readonly AnyTreeNodePrimitive[])
+  TChildren extends readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]
 > {
   readonly data: TData;
-  readonly children: TChildren;
+  readonly children: TChildren | (() => TChildren);
 }
 
 /**
@@ -54,7 +95,7 @@ export interface TreeNodeConfig<
 export class TreeNodePrimitive<
   TType extends string,
   TData extends StructPrimitive<any>,
-  TChildren extends readonly AnyTreeNodePrimitive[] | (() => readonly AnyTreeNodePrimitive[])
+  TChildren extends AnyTreeNodePrimitive = AnyTreeNodePrimitive
 > {
   readonly _tag = "TreeNodePrimitive" as const;
   readonly _Type!: TType;
@@ -63,10 +104,10 @@ export class TreeNodePrimitive<
 
   private readonly _type: TType;
   private readonly _data: TData;
-  private readonly _children: TChildren;
+  private readonly _children: TreeNodeChildrenInput;
   private _resolvedChildren: readonly AnyTreeNodePrimitive[] | undefined;
 
-  constructor(type: TType, config: TreeNodeConfig<TData, TChildren>) {
+  constructor(type: TType, config: TreeNodeConfig<TData, readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]>) {
     this._type = type;
     this._data = config.data;
     this._children = config.children;
@@ -82,14 +123,14 @@ export class TreeNodePrimitive<
     return this._data;
   }
 
-  /** Get resolved children (resolves lazy thunk if needed) */
+  /** Get resolved children (resolves lazy thunk if needed, replaces Self with this node) */
   get children(): readonly AnyTreeNodePrimitive[] {
     if (this._resolvedChildren === undefined) {
-      if (typeof this._children === "function") {
-        this._resolvedChildren = (this._children as () => readonly AnyTreeNodePrimitive[])();
-      } else {
-        this._resolvedChildren = this._children as readonly AnyTreeNodePrimitive[];
-      }
+      const resolved = typeof this._children === "function"
+        ? (this._children as () => readonly AnyTreeNodePrimitive[])()
+        : this._children;
+      // Replace Self placeholders with this node
+      this._resolvedChildren = resolved.map(child => isSelf(child) ? this : child) as readonly AnyTreeNodePrimitive[];
     }
     return this._resolvedChildren;
   }
@@ -104,10 +145,10 @@ export class TreeNodePrimitive<
 export const TreeNode = <
   TType extends string,
   TData extends StructPrimitive<any>,
-  TChildren extends readonly AnyTreeNodePrimitive[] | (() => readonly AnyTreeNodePrimitive[])
+  const TChildren extends readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]
 >(
   type: TType,
   config: TreeNodeConfig<TData, TChildren>
-): TreeNodePrimitive<TType, TData, TChildren> =>
-  new TreeNodePrimitive(type, config);
+): TreeNodePrimitive<TType, TData, ResolveChildrenUnion<TChildren, TreeNodePrimitive<TType, TData, any>>> =>
+  new TreeNodePrimitive(type, config) as TreeNodePrimitive<TType, TData, ResolveChildrenUnion<TChildren, TreeNodePrimitive<TType, TData, any>>>;
 

package/src/primitives/Union.ts

@@ -33,7 +33,7 @@ export type InferUnionSnapshot<TVariants extends UnionVariants> = {
 /**
  * Proxy for accessing union variants
  */
-export interface UnionProxy<TVariants extends UnionVariants, TDiscriminator extends string, TDefined extends boolean = false> {
+export interface UnionProxy<TVariants extends UnionVariants, _TDiscriminator extends string, TDefined extends boolean = false> {
   /** Gets the current union value */
   get(): MaybeUndefined<InferUnionState<TVariants>, TDefined>;
   

package/src/server/errors.ts

@@ -19,7 +19,7 @@ export class MimicServerError extends Error {
  * Error thrown when a transaction fails validation.
  */
 export class ValidationError extends MimicServerError {
-  readonly _tag = "ValidationError";
+  override readonly _tag = "ValidationError";
   readonly transactionId: string;
 
   constructor(transactionId: string, message: string) {
@@ -33,7 +33,7 @@ export class ValidationError extends MimicServerError {
  * Error thrown when an operation is invalid for the current schema.
  */
 export class InvalidOperationError extends MimicServerError {
-  readonly _tag = "InvalidOperationError";
+  override readonly _tag = "InvalidOperationError";
   readonly operationKind: string;
   readonly path: string;
 
@@ -49,9 +49,9 @@ export class InvalidOperationError extends MimicServerError {
  * Error thrown when an operation cannot be applied to the current state.
  */
 export class StateValidationError extends MimicServerError {
-  readonly _tag = "StateValidationError";
+  override readonly _tag = "StateValidationError";
   readonly transactionId: string;
-  readonly cause?: Error;
+  override readonly cause?: Error;
 
   constructor(transactionId: string, message: string, cause?: Error) {
     super(`Transaction ${transactionId} cannot be applied to current state: ${message}`);
@@ -65,7 +65,7 @@ export class StateValidationError extends MimicServerError {
  * Error thrown when attempting to apply an empty transaction.
  */
 export class EmptyTransactionError extends MimicServerError {
-  readonly _tag = "EmptyTransactionError";
+  override readonly _tag = "EmptyTransactionError";
   readonly transactionId: string;
 
   constructor(transactionId: string) {
@@ -79,7 +79,7 @@ export class EmptyTransactionError extends MimicServerError {
  * Error thrown when a duplicate transaction is submitted.
  */
 export class DuplicateTransactionError extends MimicServerError {
-  readonly _tag = "DuplicateTransactionError";
+  override readonly _tag = "DuplicateTransactionError";
   readonly transactionId: string;
 
   constructor(transactionId: string) {