@signalium/query 0.0.0

package/src/errors.ts

@@ -0,0 +1,124 @@
+import {
+  ARRAY_KEY,
+  ArrayDef,
+  EntityDef,
+  Mask,
+  ObjectDef,
+  RECORD_KEY,
+  RecordDef,
+  ObjectFieldTypeDef,
+  UnionDef,
+} from './types.js';
+
+export function typeToString(type: ObjectFieldTypeDef): string {
+  // Handle Set-based constants/enums
+  if (type instanceof Set) {
+    const values = Array.from(type).map(v => (typeof v === 'string' ? `"${v}"` : String(v)));
+    return values.join(' | ');
+  }
+
+  // Handle constants
+  if (typeof type === 'string') {
+    return `"${type}"`;
+  }
+
+  if (typeof type === 'boolean') {
+    return String(type);
+  }
+
+  // Handle primitive masks
+  if (typeof type === 'number') {
+    const types: string[] = [];
+
+    if (type & Mask.UNDEFINED) types.push('undefined');
+    if (type & Mask.NULL) types.push('null');
+    if (type & Mask.NUMBER) types.push('number');
+    if (type & Mask.STRING) types.push('string');
+    if (type & Mask.BOOLEAN) types.push('boolean');
+    if (type & Mask.OBJECT) types.push('object');
+    if (type & Mask.ARRAY) types.push('array');
+
+    if (types.length === 0) {
+      return 'unknown';
+    }
+
+    return types.length === 1 ? types[0] : types.join(' | ');
+  }
+
+  // Handle complex types - CHECK UNION FIRST since it contains other types
+  const mask = type.mask;
+
+  if (mask & Mask.UNION) {
+    const unionType = type as UnionDef;
+    const parts: string[] = [];
+
+    // Add primitive types from the mask
+    if (mask & Mask.UNDEFINED) parts.push('undefined');
+    if (mask & Mask.NULL) parts.push('null');
+    if (mask & Mask.NUMBER) parts.push('number');
+    if (mask & Mask.STRING) parts.push('string');
+    if (mask & Mask.BOOLEAN) parts.push('boolean');
+
+    // Add const/enum values from the values Set
+    if (unionType.values !== undefined && unionType.values.size > 0) {
+      for (const val of unionType.values) {
+        const valStr = typeof val === 'string' ? `"${val}"` : String(val);
+        parts.push(valStr);
+      }
+    }
+
+    // Add complex types from the shape object
+    if (unionType.shape !== undefined) {
+      if (unionType.shape[ARRAY_KEY] !== undefined) {
+        parts.push(`Array<${typeToString(unionType.shape[ARRAY_KEY] as ObjectFieldTypeDef)}>`);
+      }
+
+      if (unionType.shape[RECORD_KEY] !== undefined) {
+        parts.push(`Record<string, ${typeToString(unionType.shape[RECORD_KEY] as ObjectFieldTypeDef)}>`);
+      }
+
+      // Add entity/object types by typename
+      for (const [key, value] of Object.entries(unionType.shape)) {
+        if (key !== (ARRAY_KEY as any) && key !== (RECORD_KEY as any)) {
+          // key is the typename value (e.g., "User", "Post")
+          parts.push(key);
+        }
+      }
+    }
+
+    if (parts.length === 0) {
+      return 'union';
+    }
+
+    return parts.join(' | ');
+  }
+
+  if (mask & Mask.ENTITY) {
+    return `Entity<${(type as EntityDef).typenameValue}>`;
+  }
+
+  if (mask & Mask.ARRAY) {
+    const shape = (type as ArrayDef).shape;
+    return `Array<${typeToString(shape)}>`;
+  }
+
+  if (mask & Mask.RECORD) {
+    const shape = (type as RecordDef).shape;
+    return `Record<string, ${typeToString(shape)}>`;
+  }
+
+  if (mask & Mask.OBJECT) {
+    const typename = (type as ObjectDef).typenameValue;
+    return typename ? `Object<${typename}>` : 'object';
+  }
+
+  return 'unknown';
+}
+
+export function typeError(path: string, expectedType: ObjectFieldTypeDef, value: unknown): Error {
+  return new TypeError(
+    `Validation error at ${path}: expected ${typeToString(expectedType)}, got ${
+      typeof value === 'object' ? (value === null ? 'null' : Array.isArray(value) ? 'array' : 'object') : typeof value
+    }`,
+  );
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+
+export { QueryClient, QueryResultImpl as QueryResult } from './QueryClient.js';
+export type { QueryContext } from './QueryClient.js';
+export type { QueryStore } from './QueryStore.js';
+export { query } from './query.js';
+export type { ExtractType } from './query.js';

package/src/parseEntities.ts

@@ -0,0 +1,213 @@
+// -----------------------------------------------------------------------------
+// Entity System
+// -----------------------------------------------------------------------------
+
+import { hashValue } from 'signalium/utils';
+import { QueryClient } from './QueryClient.js';
+import {
+  ARRAY_KEY,
+  ArrayDef,
+  ComplexTypeDef,
+  EntityDef,
+  Mask,
+  ObjectDef,
+  RECORD_KEY,
+  RecordDef,
+  UnionDef,
+} from './types.js';
+import { extractShape, typeMaskOf } from './utils.js';
+
+const entries = Object.entries;
+
+export function parseUnionEntities(
+  valueType: number,
+  value: object | unknown[],
+  unionDef: UnionDef,
+  queryClient: QueryClient,
+  entityRefs?: Set<number>,
+): unknown {
+  if (valueType === Mask.ARRAY) {
+    const shape = unionDef.shape![ARRAY_KEY];
+
+    if (shape === undefined || typeof shape === 'number') {
+      return value;
+    }
+
+    return parseArrayEntities(
+      value as unknown[],
+      { mask: Mask.ARRAY, shape, values: undefined } as ArrayDef,
+      queryClient,
+      entityRefs,
+    );
+  } else {
+    // Use the cached typename field from the union definition
+    const typenameField = unionDef.typenameField;
+    const typename = typenameField ? (value as Record<string, unknown>)[typenameField] : undefined;
+
+    if (typename === undefined || typeof typename !== 'string') {
+      const recordShape = unionDef.shape![RECORD_KEY];
+
+      if (recordShape === undefined || typeof recordShape === 'number') {
+        return value;
+      }
+
+      return parseRecordEntities(
+        value as Record<string, unknown>,
+        recordShape as ComplexTypeDef,
+        queryClient,
+        entityRefs,
+      );
+    }
+
+    const matchingDef = unionDef.shape![typename];
+
+    if (matchingDef === undefined || typeof matchingDef === 'number') {
+      return value;
+    }
+
+    return parseObjectEntities(
+      value as Record<string, unknown>,
+      matchingDef as ObjectDef | EntityDef,
+      queryClient,
+      entityRefs,
+    );
+  }
+}
+
+export function parseArrayEntities(
+  array: unknown[],
+  arrayShape: ComplexTypeDef,
+  queryClient: QueryClient,
+  entityRefs?: Set<number>,
+): unknown[] {
+  for (let i = 0; i < array.length; i++) {
+    array[i] = parseEntities(array[i], arrayShape, queryClient, entityRefs);
+  }
+
+  return array;
+}
+
+export function parseRecordEntities(
+  record: Record<string, unknown>,
+  recordShape: ComplexTypeDef,
+  queryClient: QueryClient,
+  entityRefs?: Set<number>,
+): Record<string, unknown> {
+  if (typeof recordShape === 'number') {
+    return record;
+  }
+
+  for (const [key, value] of entries(record)) {
+    record[key] = parseEntities(value, recordShape, queryClient, entityRefs);
+  }
+
+  return record;
+}
+
+export function parseObjectEntities(
+  obj: Record<string, unknown>,
+  objectShape: ObjectDef | EntityDef,
+  queryClient: QueryClient,
+  entityRefs?: Set<number>,
+): Record<string, unknown> {
+  const entityRefId = obj.__entityRef as number;
+
+  // Check if this is an entity reference (from cache)
+  if (typeof entityRefId === 'number') {
+    return queryClient.hydrateEntity(entityRefId, objectShape as EntityDef).proxy;
+  }
+
+  // Process sub-entity paths (only these paths can contain entities)
+  const { mask } = objectShape;
+
+  const childRefs = mask & Mask.ENTITY ? new Set<number>() : entityRefs;
+
+  // Extract shape first to resolve lazy definitions and set subEntityPaths
+  const shape = extractShape(objectShape);
+  const subEntityPaths = objectShape.subEntityPaths;
+
+  if (subEntityPaths !== undefined) {
+    if (typeof subEntityPaths === 'string') {
+      // Single path - avoid array allocation
+      const propDef = shape[subEntityPaths];
+      obj[subEntityPaths] = parseEntities(obj[subEntityPaths], propDef as ComplexTypeDef, queryClient, childRefs);
+    } else {
+      // Multiple paths - iterate directly
+      for (const path of subEntityPaths) {
+        const propDef = shape[path];
+        obj[path] = parseEntities(obj[path], propDef as ComplexTypeDef, queryClient, childRefs);
+      }
+    }
+  }
+
+  // Handle entity replacement (entities get cached and replaced with proxies)
+  if (mask & Mask.ENTITY) {
+    const entityDef = objectShape as EntityDef;
+    const typename = entityDef.typenameValue;
+    const id = obj[entityDef.idField];
+
+    const desc = `${typename}:${id}`;
+    const key = hashValue(desc);
+
+    // Add this entity's key to the parent's entityRefs (if provided)
+    if (entityRefs !== undefined) {
+      entityRefs.add(key);
+    }
+
+    return queryClient.saveEntity(key, obj, entityDef, childRefs).proxy;
+  }
+
+  // Return the processed object (even if not an entity)
+  return obj;
+}
+
+export function parseEntities(
+  value: unknown,
+  def: ComplexTypeDef,
+  queryClient: QueryClient,
+  entityRefs?: Set<number>,
+): unknown {
+  const valueType = typeMaskOf(value);
+  const defType = def.mask;
+
+  // Skip primitives and incompatible types - they can't contain entities
+  // Note: We silently return incompatible values rather than erroring
+  if (valueType < Mask.OBJECT || (defType & valueType) === 0) {
+    return value;
+  }
+
+  // Handle unions first - they can contain multiple types, and all of the union
+  // logic is handled above, so we return early here if it's a union
+  if ((defType & Mask.UNION) !== 0) {
+    return parseUnionEntities(
+      valueType,
+      value as Record<string, unknown> | unknown[],
+      def as UnionDef,
+      queryClient,
+      entityRefs,
+    );
+  }
+
+  // If it's not a union, AND the value IS an array, then the definition must
+  // be an ArrayDef, so we can cast safely here
+  if (valueType === Mask.ARRAY) {
+    return parseArrayEntities(value as unknown[], (def as ArrayDef).shape as ComplexTypeDef, queryClient, entityRefs);
+  }
+
+  // Now we know the value is an object, so def must be a RecordDef, ObjectDef
+  // or EntityDef. We first check to see if it's a RecordDef, and if so, we can
+  // cast it here and return early.
+  if ((defType & Mask.RECORD) !== 0) {
+    return parseRecordEntities(
+      value as Record<string, unknown>,
+      (def as RecordDef).shape as ComplexTypeDef,
+      queryClient,
+      entityRefs,
+    );
+  }
+
+  // Now we know the def is an ObjectDef or EntityDef. These are both handled
+  // the same way _mostly_, with Entities just returning a proxy instead of the
+  // object itself
+  return parseObjectEntities(value as Record<string, unknown>, def as ObjectDef | EntityDef, queryClient, entityRefs);
+}

package/src/pathInterpolator.ts

@@ -0,0 +1,74 @@
+/**
+ * Path interpolation utilities for URL templates with parameter substitution.
+ *
+ * Converts path templates like "/users/{userId}/posts/{postId}" into functions
+ * that efficiently interpolate parameter values.
+ *
+ * The implementation pre-parses the path template once into segments and parameter
+ * keys, then uses simple string concatenation at runtime for optimal performance.
+ */
+
+export type PathInterpolator = (params: Record<string, any>) => string;
+
+/**
+ * Creates an optimized path interpolation function from a URL template.
+ *
+ * The template uses curly braces for parameters (e.g., "/items/{id}").
+ * Parameter values are URL-encoded when interpolated. Any parameters not
+ * found in the path template are appended as query string parameters.
+ *
+ * @param pathTemplate - URL template with {paramName} placeholders
+ * @returns Function that interpolates parameters into the path with search params
+ *
+ * @example
+ * ```ts
+ * const interpolate = createPathInterpolator('/users/{userId}/posts/{postId}');
+ * const url = interpolate({ userId: '123', postId: '456', page: 2, limit: 10 });
+ * // Returns: "/users/123/posts/456?page=2&limit=10"
+ * ```
+ */
+export function createPathInterpolator(pathTemplate: string): PathInterpolator {
+  // Pre-parse path into segments and param keys (parse once, concatenate many times)
+  const segments: string[] = [];
+  const paramKeys: string[] = [];
+  const paramKeysSet = new Set<string>();
+  let lastIndex = 0;
+  const paramRegex = /\[([^\]]+)\]/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = paramRegex.exec(pathTemplate)) !== null) {
+    segments.push(pathTemplate.slice(lastIndex, match.index));
+    paramKeys.push(match[1]);
+    paramKeysSet.add(match[1]);
+    lastIndex = paramRegex.lastIndex;
+  }
+  segments.push(pathTemplate.slice(lastIndex));
+
+  // Return optimized interpolation function with pre-parsed segments
+  return (params: Record<string, any>): string => {
+    // Build the path with interpolated path parameters
+    let result = segments[0];
+    for (let i = 0; i < paramKeys.length; i++) {
+      result += encodeURIComponent(String(params[paramKeys[i]])) + segments[i + 1];
+    }
+
+    // Collect remaining parameters as search params
+    let searchParams: URLSearchParams | null = null;
+    for (const key in params) {
+      if (!paramKeysSet.has(key) && params[key] !== undefined) {
+        if (searchParams === null) {
+          searchParams = new URLSearchParams();
+        }
+
+        searchParams.append(key, String(params[key]));
+      }
+    }
+
+    // Append search params if any exist
+    if (searchParams !== null) {
+      result += '?' + searchParams.toString();
+    }
+
+    return result;
+  };
+}

package/src/proxy.ts

@@ -0,0 +1,257 @@
+import { typeError } from './errors.js';
+import { getFormat } from './typeDefs.js';
+import {
+  ARRAY_KEY,
+  ArrayDef,
+  ComplexTypeDef,
+  EntityDef,
+  Mask,
+  ObjectDef,
+  RECORD_KEY,
+  ObjectFieldTypeDef,
+  UnionDef,
+  TypeDef,
+} from './types.js';
+import { extractShape, typeMaskOf } from './utils.js';
+import { PreloadedEntityRecord } from './EntityMap.js';
+
+const entries = Object.entries;
+
+const PROXY_BRAND = new WeakSet();
+
+function parseUnionValue(
+  valueType: number,
+  value: Record<string, unknown> | unknown[],
+  unionDef: UnionDef,
+  path: string,
+): unknown {
+  if (valueType === Mask.ARRAY) {
+    const shape = unionDef.shape![ARRAY_KEY];
+
+    if (shape === undefined || typeof shape === 'number') {
+      return value;
+    }
+
+    return parseArrayValue(value as unknown[], shape, path);
+  } else {
+    // Use the cached typename field from the union definition
+    const typenameField = unionDef.typenameField;
+    const typename = typenameField ? (value as Record<string, unknown>)[typenameField] : undefined;
+
+    if (typename === undefined || typeof typename !== 'string') {
+      const recordShape = unionDef.shape![RECORD_KEY];
+
+      if (recordShape === undefined || typeof recordShape === 'number') {
+        return value;
+      }
+
+      return parseRecordValue(value as Record<string, unknown>, recordShape as ComplexTypeDef, path);
+    }
+
+    const matchingDef = unionDef.shape![typename];
+
+    if (matchingDef === undefined || typeof matchingDef === 'number') {
+      return value;
+    }
+
+    return parseObjectValue(value as Record<string, unknown>, matchingDef as ObjectDef | EntityDef, path);
+  }
+}
+
+export function parseArrayValue(array: unknown[], arrayShape: TypeDef, path: string) {
+  for (let i = 0; i < array.length; i++) {
+    array[i] = parseValue(array[i], arrayShape, `${path}[${i}]`);
+  }
+
+  return array;
+}
+
+export function parseRecordValue(record: Record<string, unknown>, recordShape: ComplexTypeDef, path: string) {
+  for (const [key, value] of entries(record)) {
+    record[key] = parseValue(value, recordShape, `${path}["${key}"]`);
+  }
+
+  return record;
+}
+
+export function parseObjectValue(object: Record<string, unknown>, objectShape: ObjectDef | EntityDef, path: string) {
+  if (PROXY_BRAND.has(object)) {
+    // Is an entity proxy, so return it directly
+    return object;
+  }
+
+  const shape = extractShape(objectShape);
+
+  for (const [key, propShape] of entries(shape)) {
+    // parse and replace the property in place
+    object[key] = parseValue(object[key], propShape, `${path}.${key}`);
+  }
+
+  return object;
+}
+
+export function parseValue(value: unknown, propDef: ObjectFieldTypeDef, path: string): unknown {
+  // Handle Set-based constants/enums
+  if (propDef instanceof Set) {
+    if (!propDef.has(value as string | boolean | number)) {
+      throw typeError(path, propDef as any, value);
+    }
+    return value;
+  }
+
+  switch (typeof propDef) {
+    case 'string':
+      if (value !== propDef) {
+        throw typeError(path, propDef, value);
+      }
+
+      return value;
+
+    // handle primitives
+    case 'number': {
+      let valueType = typeMaskOf(value);
+
+      if ((propDef & valueType) === 0) {
+        throw typeError(path, propDef, value);
+      }
+
+      if ((propDef & Mask.HAS_NUMBER_FORMAT) !== 0 && valueType === Mask.NUMBER) {
+        return getFormat(propDef)(value);
+      }
+
+      if ((propDef & Mask.HAS_STRING_FORMAT) !== 0 && valueType === Mask.STRING) {
+        return getFormat(propDef)(value);
+      }
+      return value;
+    }
+
+    // handle complex objects
+    default: {
+      // Note: Keep in mind that at this point, we're using `valueType`
+      // primarily, so some of the logic is "reversed" from the above where
+      // we use the `propDef` type primarily
+      let valueType = typeMaskOf(value);
+      const propMask = propDef.mask;
+
+      // Check if the value type is allowed by the propMask
+      // Also check if it's in a values set (for enums/constants stored in ValidatorDef)
+      if ((propMask & valueType) === 0 && !propDef.values?.has(value as string | boolean | number)) {
+        throw typeError(path, propMask, value);
+      }
+
+      if (valueType < Mask.OBJECT) {
+        if ((propMask & Mask.HAS_NUMBER_FORMAT) !== 0 && valueType === Mask.NUMBER) {
+          return getFormat(propMask)(value);
+        }
+
+        if ((propMask & Mask.HAS_STRING_FORMAT) !== 0 && valueType === Mask.STRING) {
+          return getFormat(propMask)(value);
+        }
+
+        // value is a primitive, it has already passed the mask so return it now
+        return value;
+      }
+
+      if ((valueType & Mask.UNION) !== 0) {
+        return parseUnionValue(valueType, value as Record<string, unknown> | unknown[], propDef as UnionDef, path);
+      }
+
+      if (valueType === Mask.ARRAY) {
+        return parseArrayValue(value as unknown[], propDef.shape as ComplexTypeDef, path);
+      }
+
+      return parseObjectValue(value as Record<string, unknown>, propDef as ObjectDef | EntityDef, path);
+    }
+  }
+}
+
+const CustomNodeInspect = Symbol.for('nodejs.util.inspect.custom');
+
+export function createEntityProxy(
+  id: number,
+  entityRecord: PreloadedEntityRecord,
+  def: ObjectDef | EntityDef,
+  desc?: string,
+): Record<string, unknown> {
+  // Cache for nested proxies - each proxy gets its own cache
+  const shape = extractShape(def);
+
+  const toJSON = () => ({
+    __entityRef: id,
+  });
+
+  const handler: ProxyHandler<any> = {
+    get(target, prop) {
+      // Handle toJSON for serialization
+      if (prop === 'toJSON') {
+        return toJSON;
+      }
+
+      const { signal, cache } = entityRecord;
+      const obj = signal.value;
+
+      // Check cache first, BEFORE any expensive checks
+      if (cache.has(prop)) {
+        return cache.get(prop);
+      }
+
+      let value = obj[prop as string];
+      let propDef = shape[prop as string];
+
+      if (!Object.hasOwnProperty.call(shape, prop)) {
+        return value;
+      }
+
+      const parsed = parseValue(value, propDef, `[[${desc}]].${prop as string}`);
+
+      cache.set(prop, parsed);
+
+      return parsed;
+    },
+
+    has(target, prop) {
+      return prop in shape;
+    },
+
+    ownKeys(target) {
+      const keys = Object.keys(shape);
+      // Add typename field if it exists on the definition
+      const typenameField = (def as ObjectDef | EntityDef).typenameField;
+      if (typenameField && !keys.includes(typenameField)) {
+        keys.push(typenameField);
+      }
+      return keys;
+    },
+
+    getOwnPropertyDescriptor(target, prop) {
+      const typenameField = (def as ObjectDef | EntityDef).typenameField;
+      if (prop in shape || prop === typenameField) {
+        return {
+          enumerable: true,
+          configurable: true,
+        };
+      }
+      return undefined;
+    },
+  };
+
+  const proxy = new Proxy(
+    {
+      [CustomNodeInspect]: () => {
+        return Object.keys(shape).reduce(
+          (acc, key) => {
+            acc[key] = proxy[key];
+            return acc;
+          },
+          {} as Record<string, unknown>,
+        );
+      },
+    },
+    handler,
+  );
+
+  // Add the proxy to the proxy brand set so we can easily identify it later
+  PROXY_BRAND.add(proxy);
+
+  return proxy;
+}