Core Types

type SimpleCapability = "timestamps" | "audit" | "trash" | "archivable";

type AccessLevel = "viewer" | "editor" | "owner";

type ShareableCapability = {
  shareable: {
    levels: AccessLevel[];
    default: "private" | "shared";
  };
};

type CapabilityEntry = SimpleCapability | ShareableCapability;

type SchemaCapabilities = CapabilityEntry[];

type ResourceCapabilities = CapabilityEntry[] | { exclude: SimpleCapability[] };

type RelationSimpleCapability = "timestamps" | "audit";

type DatafnSchema = {
  capabilities?: SchemaCapabilities;
  resources: DatafnResourceSchema[];
  relations?: DatafnRelationSchema[];
  namespaced?: boolean;
};

type DatafnResourceSchema = {
  name: string;
  version: number;
  idPrefix?: string;
  isRemoteOnly?: boolean;
  capabilities?: ResourceCapabilities;
  fields: DatafnFieldSchema[];
  indices?:
    | { base?: string[]; search?: string[]; vector?: string[] }
    | string[];
  permissions?: DatafnPermissionsPolicy;
};

type DatafnFieldSchema = {
  name: string;
  type: "string" | "number" | "boolean" | "object" | "array" | "date" | "file" | "json";
  required: boolean;
  nullable?: boolean;
  readonly?: boolean;
  default?: unknown;
  enum?: unknown[];
  min?: number;
  max?: number;
  minLength?: number;
  maxLength?: number;
  pattern?: string;
  unique?: boolean | string;
  encrypt?: boolean;
  volatile?: boolean;
};

type DatafnRelationSchema = {
  from: string | string[];
  to: string | string[];
  type: "one-many" | "many-one" | "many-many" | "htree";
  relation?: string;
  inverse?: string;
  cache?: boolean;
  metadata?: Array<{
    name: string;
    type: "string" | "number" | "boolean" | "date" | "object" | "json";
  }>;
  fkField?: string;
  pathField?: string;
  joinTable?: string;
  joinColumns?: { from: string; to: string };
  capabilities?: RelationSimpleCapability[];
};

interface DatafnEvent {
  type:
    | "mutation_applied"
    | "mutation_rejected"
    | "sync_applied"
    | "sync_failed"
    | "sync_retry"
    | "connectivity_changed"
    | "ws_connected"
    | "ws_disconnected";
  resource?: string;
  ids?: string[];
  mutationId?: string;
  clientId?: string;
  timestampMs: number;
  context?: unknown;
  action?: string;
  fields?: string[];
  system?: boolean;
  fromRemoteTab?: boolean;
}

type DatafnEventFilter = Partial<{
  type: DatafnEvent["type"] | Array<DatafnEvent["type"]>;
  resource: string | string[];
  ids: string | string[];
  mutationId: string | string[];
  action: string | string[];
  fields: string | string[];
  contextKeys: string[];
  context: Record<string, unknown>;
}>;

interface DatafnSignal<T> {
  get(): T;
  subscribe(handler: (value: T) => void): () => void;
  readonly loading: boolean;
  readonly error: DatafnError | null;
  readonly refreshing: boolean;
  readonly nextCursor: string | null | undefined;
  dispose(): void;
}

interface DatafnPlugin {
  name: string;
  runsOn: Array<"client" | "server">;
  beforeQuery?: (ctx: DatafnHookContext, q: unknown) => Promise<unknown> | unknown;
  afterQuery?: (ctx: DatafnHookContext, q: unknown, result: unknown) => Promise<unknown> | unknown;
  beforeMutation?: (ctx: DatafnHookContext, m: unknown | unknown[]) => Promise<unknown> | unknown;
  afterMutation?: (ctx: DatafnHookContext, m: unknown | unknown[], result: unknown) => Promise<void> | void;
  beforeSync?: (ctx: DatafnHookContext, phase: string, payload: unknown) => Promise<unknown> | unknown;
  afterSync?: (ctx: DatafnHookContext, phase: string, payload: unknown, result: unknown) => Promise<void> | void;
}

type DatafnLimitsConfig = {
  maxLimit?: number;
  maxTransactSteps?: number;
  maxPayloadBytes?: number;
  maxPullLimit?: number;
  maxBatchSize?: number;
  maxCloneRecords?: number;
  idempotencyTtlMs?: number;
  idempotencyMaxEntries?: number;
  maxSelectTokens?: number;
  maxFilterKeysPerLevel?: number;
  maxSortFields?: number;
  maxAggregations?: number;
  maxSearchQueryLength?: number;
  maxLikePatternLength?: number;
  maxIdLength?: number;
  maxFilterDepth?: number;
};

type DatafnWsConfig = {
  maxConnections?: number;
  maxConnectionsPerNamespace?: number;
  heartbeatIntervalMs?: number;
  heartbeatTimeoutMs?: number;
};

type DatafnPermissionsPolicy = {
  read?: { fields: string[] };
  write?: { fields: string[] };
  ownerField?: string;
};