@signalium/query 0.0.0

package/src/react/__tests__/utils.tsx

@@ -0,0 +1,71 @@
+import React from 'react';
+
+/**
+ * Helper utilities for React tests in the query package
+ */
+
+export interface RenderCounter<Props extends Record<string, unknown>> {
+  (props: Props): React.ReactNode;
+  testId: number;
+  renderCount: number;
+}
+
+let CURRENT_ID = 0;
+
+export type ComponentType<P = any> = (props: P) => React.ReactNode;
+export type HOC<InProps = any, OutProps = InProps> = (Component: ComponentType<InProps>) => ComponentType<OutProps>;
+
+/**
+ * The wrapper passed to createRenderCounter is a HOC that will wrap the component
+ * with additional functionality. The reason we don't pass a component directly is
+ * because introducing additional components would mess with the real render counts.
+ */
+const EmptyWrapper: HOC = Component => props => Component(props);
+
+/**
+ * Creates a component that tracks how many times it renders.
+ * Useful for verifying that components only re-render when expected.
+ */
+export function createRenderCounter<Props extends Record<string, unknown>>(
+  Component: (props: Props) => React.ReactNode,
+  wrapper: HOC<Props> = EmptyWrapper,
+): RenderCounter<Props> {
+  const id = CURRENT_ID++;
+
+  const RenderCounterComponent = wrapper((props: Props) => {
+    RenderCounterComponent.renderCount++;
+
+    // Call the component manually so it's not a separate React component
+    const children = Component(props);
+
+    return <div data-testid={id}>{children}</div>;
+  }) as RenderCounter<Props>;
+
+  RenderCounterComponent.testId = id;
+  RenderCounterComponent.renderCount = 0;
+
+  return RenderCounterComponent;
+}
+
+/**
+ * Mock user data factory
+ */
+export function createUser(id: number, overrides?: Partial<{ name: string; email: string }>) {
+  return {
+    id,
+    name: overrides?.name ?? `User ${id}`,
+    email: overrides?.email ?? `user${id}@example.com`,
+  };
+}
+
+/**
+ * Mock post data factory
+ */
+export function createPost(id: number, authorId: number, overrides?: Partial<{ title: string; content: string }>) {
+  return {
+    id,
+    authorId,
+    title: overrides?.title ?? `Post ${id}`,
+    content: overrides?.content ?? `Content for post ${id}`,
+  };
+}

package/src/typeDefs.ts

@@ -0,0 +1,351 @@
+import {
+  APITypes,
+  ARRAY_KEY,
+  ArrayDef,
+  ComplexTypeDef,
+  EntityDef,
+  Mask,
+  ObjectDef,
+  ObjectShape,
+  RECORD_KEY,
+  RecordDef,
+  TypeDef,
+  ObjectFieldTypeDef,
+  UnionDef,
+  UnionTypeDefs,
+} from './types.js';
+import { extractShape, extractShapeMetadata } from './utils.js';
+
+export class ValidatorDef<T> {
+  private _optional: ValidatorDef<T | undefined> | undefined;
+  private _nullable: ValidatorDef<T | null> | undefined;
+  private _nullish: ValidatorDef<T | null | undefined> | undefined;
+
+  constructor(
+    public mask: Mask,
+    public shape: ObjectFieldTypeDef | ObjectShape | ((t: APITypes) => ObjectShape) | UnionTypeDefs | undefined,
+    public subEntityPaths: undefined | string | string[] = undefined,
+    public values: Set<string | boolean | number> | undefined = undefined,
+    public typenameField: string | undefined = undefined,
+    public typenameValue: string | undefined = undefined,
+    public idField: string | undefined = undefined,
+  ) {}
+
+  get optional(): ValidatorDef<T | undefined> {
+    if (this._optional === undefined) {
+      this._optional = new ValidatorDef(
+        this.mask | Mask.UNDEFINED,
+        this.shape,
+        this.subEntityPaths,
+        this.values,
+        this.typenameField,
+        this.typenameValue,
+        this.idField,
+      );
+    }
+    return this._optional;
+  }
+
+  get nullable(): ValidatorDef<T | null> {
+    if (this._nullable === undefined) {
+      this._nullable = new ValidatorDef(
+        this.mask | Mask.NULL,
+        this.shape,
+        this.subEntityPaths,
+        this.values,
+        this.typenameField,
+        this.typenameValue,
+        this.idField,
+      );
+    }
+    return this._nullable;
+  }
+
+  get nullish(): ValidatorDef<T | null | undefined> {
+    if (this._nullish === undefined) {
+      this._nullish = new ValidatorDef(
+        this.mask | Mask.UNDEFINED | Mask.NULL,
+        this.shape,
+        this.subEntityPaths,
+        this.values,
+        this.typenameField,
+        this.typenameValue,
+        this.idField,
+      );
+    }
+    return this._nullish;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Complex Type Definitions
+// -----------------------------------------------------------------------------
+
+export function defineArray<T extends TypeDef>(shape: T): ArrayDef<T> {
+  let mask = Mask.ARRAY;
+
+  // Propagate HAS_SUB_ENTITY flag if the shape contains entities
+  if (shape instanceof ValidatorDef && (shape.mask & (Mask.ENTITY | Mask.HAS_SUB_ENTITY)) !== 0) {
+    mask |= Mask.HAS_SUB_ENTITY;
+  }
+
+  return new ValidatorDef(mask, shape) as unknown as ArrayDef<T>;
+}
+
+export function defineRecord<T extends TypeDef>(shape: T): RecordDef<T> {
+  // The mask should be OBJECT | RECORD so that values match when compared
+  let mask = Mask.RECORD | Mask.OBJECT;
+
+  // Propagate HAS_SUB_ENTITY flag if the shape contains entities
+  if (shape instanceof ValidatorDef && (shape.mask & (Mask.ENTITY | Mask.HAS_SUB_ENTITY)) !== 0) {
+    mask |= Mask.HAS_SUB_ENTITY;
+  }
+
+  return new ValidatorDef(mask, shape) as unknown as RecordDef<T>;
+}
+
+export function defineObject<T extends ObjectShape>(shape: T): ObjectDef<T> {
+  const def = new ValidatorDef(Mask.OBJECT, shape);
+
+  extractShapeMetadata(def, shape);
+
+  return def as unknown as ObjectDef<T>;
+}
+
+const addShapeToUnion = (
+  shape: UnionTypeDefs,
+  definition: ObjectDef | EntityDef | RecordDef | UnionDef | ArrayDef,
+  unionTypenameField: string | undefined,
+) => {
+  const mask = definition.mask;
+
+  if ((mask & Mask.UNION) !== 0) {
+    // Merge nested union into parent union
+    const nestedUnion = definition as UnionDef;
+
+    // Check typename field consistency
+    if (nestedUnion.typenameField !== undefined) {
+      if (unionTypenameField !== undefined && unionTypenameField !== nestedUnion.typenameField) {
+        throw new Error(
+          `Union typename field conflict: Cannot merge unions with different typename fields ('${unionTypenameField}' vs '${nestedUnion.typenameField}')`,
+        );
+      }
+      unionTypenameField = nestedUnion.typenameField;
+    }
+
+    // Merge nested union's shape into parent
+    if (nestedUnion.shape !== undefined) {
+      for (const key of [...Object.keys(nestedUnion.shape), ARRAY_KEY, RECORD_KEY] as const) {
+        // Check for conflicts
+        const value = nestedUnion.shape[key];
+
+        if (shape[key] !== undefined && shape[key] !== value) {
+          throw new Error(
+            `Union merge conflict: Duplicate typename value '${String(key)}' found when merging nested unions`,
+          );
+        }
+
+        // coerce type because we know the value is the same type as the key
+        shape[key] = value as any;
+      }
+    }
+
+    return unionTypenameField;
+  } else if ((mask & Mask.ARRAY) !== 0) {
+    if (shape[ARRAY_KEY] !== undefined) {
+      throw new Error('Array shape already defined');
+    }
+
+    shape[ARRAY_KEY] = definition.shape as TypeDef;
+
+    return unionTypenameField;
+  } else if ((mask & Mask.RECORD) !== 0) {
+    if (shape[RECORD_KEY] !== undefined) {
+      throw new Error('Record shape already defined');
+    }
+
+    shape[RECORD_KEY] = definition.shape as TypeDef;
+
+    return unionTypenameField;
+  } else {
+    // Make sure the type is fully extracted, so we can get the typename field and value
+    extractShape(definition);
+
+    // definition is ObjectDef | EntityDef
+    const typenameField = (definition as ObjectDef).typenameField;
+    const typename = (definition as ObjectDef).typenameValue;
+
+    if (typename === undefined) {
+      throw new Error(
+        'Object definitions must have a typename to be in a union with other objects, records, or arrays',
+      );
+    }
+
+    if (unionTypenameField !== undefined && typenameField !== unionTypenameField) {
+      throw new Error('Object definitions must have the same typename field to be in the same union');
+    }
+
+    shape[typename] = definition as ObjectDef;
+
+    return typenameField;
+  }
+};
+
+function defineUnion<T extends readonly TypeDef[]>(...types: T): UnionDef<T> {
+  let mask = 0;
+  let definition: ObjectDef | EntityDef | RecordDef | UnionDef | ArrayDef | undefined;
+  let shape: UnionTypeDefs | undefined;
+  let values: Set<string | boolean | number> | undefined;
+  let unionTypenameField: string | undefined;
+
+  for (const type of types) {
+    if (typeof type === 'number') {
+      mask |= type;
+      continue;
+    }
+
+    const isSet = type instanceof Set;
+    const typeValues = isSet ? type : type.values;
+
+    // Handle Set-based constants/enums
+    if (typeValues !== undefined) {
+      if (values === undefined) {
+        values = new Set(typeValues);
+      } else {
+        for (const val of typeValues) {
+          values.add(val);
+        }
+      }
+
+      if (isSet) {
+        continue;
+      }
+    }
+
+    // We know it's a complex type at this point because if it was a Set,
+    // we would have already handled it above.
+    const typeDef = type as ComplexTypeDef;
+
+    mask |= typeDef.mask;
+
+    if (definition === undefined) {
+      definition = typeDef;
+      continue;
+    }
+
+    if (shape === undefined) {
+      shape = Object.create(null) as UnionTypeDefs;
+
+      unionTypenameField = addShapeToUnion(shape, definition, unionTypenameField);
+    }
+
+    unionTypenameField = addShapeToUnion(shape, typeDef, unionTypenameField);
+  }
+
+  // It was a union of primitives, so return the mask
+  if (definition === undefined && values === undefined) {
+    // This type coercion is incorrect, but we can't return the mask as a Mask
+    // because that loses the type information about the union, which breaks
+    // inference.
+    //
+    // TODO: Figure out how to make this correct type-wise
+    return mask as unknown as UnionDef<T>;
+  }
+
+  return new ValidatorDef(
+    mask | Mask.UNION,
+    shape ?? definition?.shape,
+    undefined,
+    values,
+    unionTypenameField,
+  ) as UnionDef;
+}
+
+// -----------------------------------------------------------------------------
+// Marker Functions
+// -----------------------------------------------------------------------------
+
+function defineTypename<T extends string>(value: T): T {
+  return value;
+}
+
+function defineConst<T extends string | boolean | number>(value: T): Set<T> {
+  return new Set([value]);
+}
+
+function defineEnum<T extends readonly (string | boolean | number)[]>(...values: T): Set<T[number]> {
+  return new Set(values as unknown as T[number][]);
+}
+
+// -----------------------------------------------------------------------------
+// Formatted Values
+// -----------------------------------------------------------------------------
+
+const FORMAT_MASK_SHIFT = 16;
+
+let nextFormatId = 0;
+const FORMAT_PARSERS: ((value: unknown) => unknown)[] = [];
+const FORMAT_SERIALIZERS: ((value: unknown) => unknown)[] = [];
+const FORMAT_MAP = new Map<string, number>();
+
+function defineFormatted(format: string): number {
+  const mask = FORMAT_MAP.get(format);
+
+  if (mask === undefined) {
+    throw new Error(`Format ${format} not registered`);
+  }
+
+  return mask;
+}
+
+export function getFormat(mask: number): (value: unknown) => unknown {
+  const formatId = mask >> FORMAT_MASK_SHIFT;
+
+  return FORMAT_PARSERS[formatId];
+}
+
+export function registerFormat<Input extends string | boolean, T>(
+  name: string,
+  type: Input extends string ? Mask.STRING : Mask.BOOLEAN,
+  parse: (value: Input) => T,
+  serialize: (value: T) => Input,
+) {
+  const maskId = nextFormatId++;
+  FORMAT_PARSERS[maskId] = parse as (value: unknown) => unknown;
+  FORMAT_SERIALIZERS[maskId] = serialize as (value: unknown) => unknown;
+
+  const shiftedId = maskId << FORMAT_MASK_SHIFT;
+  const formatMask = type === Mask.STRING ? Mask.HAS_STRING_FORMAT : Mask.HAS_NUMBER_FORMAT;
+  const mask = shiftedId | type | formatMask;
+
+  FORMAT_MAP.set(name, mask);
+}
+
+// -----------------------------------------------------------------------------
+// Entity Definitions
+// -----------------------------------------------------------------------------
+
+export function entity<T extends ObjectShape>(shape: (t: APITypes) => T): EntityDef<T> {
+  return new ValidatorDef(
+    // The mask should be OBJECT | ENTITY so that values match when compared
+    Mask.ENTITY | Mask.OBJECT,
+    shape,
+  ) as unknown as EntityDef<T>;
+}
+
+export const t: APITypes = {
+  format: defineFormatted,
+  typename: defineTypename,
+  const: defineConst,
+  enum: defineEnum,
+  id: Mask.ID | Mask.STRING | Mask.NUMBER,
+  string: Mask.STRING,
+  number: Mask.NUMBER,
+  boolean: Mask.BOOLEAN,
+  null: Mask.NULL,
+  undefined: Mask.UNDEFINED,
+  array: defineArray,
+  object: defineObject,
+  record: defineRecord,
+  union: defineUnion,
+};

package/src/types.ts

@@ -0,0 +1,121 @@
+import { PendingReactivePromise, ReadyReactivePromise } from 'signalium';
+import { ReactivePromise } from 'signalium';
+
+export const enum Mask {
+  // Fundamental types
+  UNDEFINED = 1 << 0,
+  NULL = 1 << 1,
+  NUMBER = 1 << 2,
+  STRING = 1 << 3,
+  BOOLEAN = 1 << 4,
+  OBJECT = 1 << 5,
+  ARRAY = 1 << 6,
+  ID = 1 << 7,
+
+  // Complex types
+  RECORD = 1 << 8,
+  UNION = 1 << 9,
+  ENTITY = 1 << 10,
+
+  // Flags
+  HAS_SUB_ENTITY = 1 << 11,
+  HAS_NUMBER_FORMAT = 1 << 12,
+  HAS_STRING_FORMAT = 1 << 13,
+}
+
+export type SimpleTypeDef =
+  // Sets are constant values
+  | Set<string | boolean | number>
+
+  // Numbers are primitive type masks (potentially multiple masks combined)
+  | Mask;
+
+export type ComplexTypeDef =
+  // Objects, arrays, records, and unions are definitions
+  ObjectDef | EntityDef | ArrayDef | RecordDef | UnionDef;
+
+export type TypeDef = SimpleTypeDef | ComplexTypeDef;
+
+export type ObjectFieldTypeDef = TypeDef | string;
+
+export type ObjectShape = Record<string, ObjectFieldTypeDef>;
+
+export const ARRAY_KEY = Symbol('array');
+export const RECORD_KEY = Symbol('record');
+
+export interface UnionTypeDefs {
+  [ARRAY_KEY]?: TypeDef;
+  [RECORD_KEY]?: TypeDef;
+  [key: string]: ObjectDef | EntityDef;
+}
+
+export interface BaseTypeDef {
+  mask: Mask;
+  typenameField: string;
+  typenameValue: string;
+  idField: string;
+  subEntityPaths: undefined | string | string[];
+  values: Set<string | boolean | number> | undefined;
+
+  optional: this | Mask.UNDEFINED;
+  nullable: this | Mask.NULL;
+  nullish: this | Mask.UNDEFINED | Mask.NULL;
+}
+
+export interface EntityDef<T extends ObjectShape = ObjectShape> extends BaseTypeDef {
+  mask: Mask.ENTITY;
+  shape: T | ((t: APITypes) => T);
+}
+
+export interface ObjectDef<T extends ObjectShape = ObjectShape> extends BaseTypeDef {
+  mask: Mask.OBJECT;
+  shape: T;
+}
+
+export interface ArrayDef<T extends TypeDef = TypeDef> extends BaseTypeDef {
+  mask: Mask.ARRAY;
+  shape: T;
+}
+
+export interface UnionDef<_T extends readonly TypeDef[] = readonly TypeDef[]> extends BaseTypeDef {
+  mask: Mask.UNION;
+  shape: UnionTypeDefs | undefined;
+}
+
+export interface RecordDef<T extends TypeDef = TypeDef> extends BaseTypeDef {
+  mask: Mask.RECORD;
+  shape: T;
+}
+
+export interface APITypes {
+  format: (format: string) => number;
+  typename: <T extends string>(value: T) => T;
+  const: <T extends string | boolean | number>(value: T) => Set<T>;
+  enum: <T extends readonly (string | boolean | number)[]>(...values: T) => Set<T[number]>;
+
+  id: Mask.ID;
+  string: Mask.STRING;
+  number: Mask.NUMBER;
+  boolean: Mask.BOOLEAN;
+  null: Mask.NULL;
+  undefined: Mask.UNDEFINED;
+
+  array: <T extends TypeDef>(shape: T) => ArrayDef<T>;
+
+  object: <T extends ObjectShape>(shape: T) => ObjectDef<T>;
+  record: <T extends TypeDef>(shape: T) => RecordDef<T>;
+
+  union: <VS extends readonly TypeDef[]>(...types: VS) => UnionDef<VS>;
+}
+
+type QueryResultExtensions<T> = {
+  refetch: () => Promise<T>;
+};
+
+export type QueryResult<T> = ReactivePromise<T> & QueryResultExtensions<T>;
+
+export type PendingQueryResult<T> = PendingReactivePromise<T> & QueryResultExtensions<T>;
+
+export type ReadyQueryResult<T> = ReadyReactivePromise<T> & QueryResultExtensions<T>;
+
+export type DiscriminatedQueryResult<T> = PendingQueryResult<T> | ReadyQueryResult<T>;

package/src/utils.ts

@@ -0,0 +1,66 @@
+import { t, ValidatorDef } from './typeDefs.js';
+import { ComplexTypeDef, EntityDef, Mask, ObjectShape } from './types.js';
+
+const entries = Object.entries;
+const isArray = Array.isArray;
+
+export function extractShapeMetadata(def: ValidatorDef<any>, shape: ObjectShape): void {
+  for (const [key, value] of Object.entries(shape)) {
+    if (value instanceof ValidatorDef && (value.mask & (Mask.ENTITY | Mask.HAS_SUB_ENTITY)) !== 0) {
+      if (def.subEntityPaths === undefined) {
+        def.subEntityPaths = key;
+      } else if (isArray(def.subEntityPaths)) {
+        def.subEntityPaths.push(key);
+      } else {
+        def.subEntityPaths = [def.subEntityPaths, key];
+      }
+    }
+    // Check if this is a typename field (plain string value)
+    if (typeof value === 'string') {
+      if (def.typenameField !== undefined) {
+        throw new Error(`Duplicate typename field: ${key}`);
+      }
+
+      def.typenameField = key;
+      def.typenameValue = value;
+    }
+    // Check if this is an id field (Mask.ID)
+    else if (typeof value === 'number' && (value & Mask.ID) !== 0) {
+      if (def.idField !== undefined) {
+        throw new Error(`Duplicate id field: ${key}`);
+      }
+
+      def.idField = key;
+    }
+  }
+}
+
+export function extractShape<T extends ComplexTypeDef>(def: T): T extends EntityDef ? ObjectShape : T['shape'] {
+  let shape = def.shape;
+
+  if (typeof shape === 'function') {
+    shape = def.shape = shape(t);
+    extractShapeMetadata(def as ValidatorDef<any>, shape);
+  }
+
+  return shape as T extends EntityDef ? ObjectShape : T['shape'];
+}
+
+export function typeMaskOf(value: unknown): Mask {
+  if (value === null) return Mask.NULL;
+
+  switch (typeof value) {
+    case 'number':
+      return Mask.NUMBER;
+    case 'string':
+      return Mask.STRING;
+    case 'boolean':
+      return Mask.BOOLEAN;
+    case 'undefined':
+      return Mask.UNDEFINED;
+    case 'object':
+      return isArray(value) ? Mask.ARRAY : Mask.OBJECT;
+    default:
+      throw new Error(`Invalid type: ${typeof value}`);
+  }
+}

package/tsconfig.cjs.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/cjs",
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": true,
+    "jsx": "react-jsx",
+    "module": "commonjs",
+    "moduleResolution": "node"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__"]
+}

package/tsconfig.esm.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/esm",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__"]
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/esm",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": {
+      "signalium": ["../signalium/src/index.ts"],
+      "signalium/utils": ["../signalium/src/utils.ts"],
+      "signalium/config": ["../signalium/src/config.ts"],
+      "signalium/debug": ["../signalium/src/debug.ts"],
+      "signalium/react": ["../signalium/src/react/index.ts"],
+      "signalium/transform": ["../signalium/src/transform/index.ts"]
+    }
+  },
+  "include": ["src", "vitest.config.ts"]
+}