@datafn/core 0.0.1

package/README.md

@@ -0,0 +1,219 @@
+# @datafn/core
+
+Core types, schema validation, and DFQL normalization for DataFn.
+
+## Installation
+
+```bash
+npm install @datafn/core
+```
+
+## Features
+
+- **Type Definitions**: Complete TypeScript types for schemas, events, signals, and plugins
+- **Schema Validation**: Runtime validation of DataFn schemas
+- **DFQL Normalization**: Deterministic normalization for cache keys
+- **Error Handling**: Structured error types with envelopes
+
+## API
+
+### Types
+
+#### DatafnSchema
+
+```typescript
+type DatafnSchema = {
+  resources: DatafnResourceSchema[];
+  relations?: DatafnRelationSchema[];
+};
+```
+
+Defines the complete data model including resources (tables) and their relationships.
+
+#### DatafnResourceSchema
+
+```typescript
+type DatafnResourceSchema = {
+  name: string;
+  version: number;
+  fields: DatafnFieldSchema[];
+  idPrefix?: string;
+  isRemoteOnly?: boolean;
+  indices?:
+    | { base?: string[]; search?: string[]; vector?: string[] }
+    | string[];
+};
+```
+
+Defines a resource (table) with fields, version, and optional indices.
+
+#### DatafnEvent
+
+```typescript
+interface DatafnEvent {
+  type:
+    | "mutation_applied"
+    | "mutation_rejected"
+    | "sync_applied"
+    | "sync_failed";
+  resource?: string;
+  ids?: string[];
+  mutationId?: string;
+  clientId?: string;
+  timestampMs: number;
+  context?: unknown;
+  action?: string;
+  fields?: string[];
+}
+```
+
+Event structure for mutation and sync operations.
+
+#### DatafnPlugin & DatafnHookContext
+
+```typescript
+type DatafnHookContext = {
+  env: "client" | "server";
+  schema: DatafnSchema;
+  context?: unknown;
+};
+
+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) => Promise<unknown> | unknown;
+  afterMutation?: (ctx: DatafnHookContext, m: unknown, result: unknown) => Promise<void> | void;
+  // ... hooks for sync (beforeSync, afterSync)
+}
+```
+
+Plugins allow intercepting and modifying queries, mutations, and sync operations.
+
+### Functions
+
+#### validateSchema(schema: unknown): DatafnEnvelope<DatafnSchema>
+
+```typescript
+import { validateSchema, unwrapEnvelope } from "@datafn/core";
+
+// Validate and unwrap (throws if invalid)
+const schema = unwrapEnvelope(
+  validateSchema({
+    resources: [
+      {
+        name: "user",
+        version: 1,
+        fields: [
+          { name: "email", type: "string", required: true },
+          { name: "name", type: "string", required: true },
+        ],
+      },
+    ],
+  }),
+);
+```
+
+Validates a schema and returns an envelope. Use `unwrapEnvelope` to get the result or throw the error.
+
+#### unwrapEnvelope<T>(env: DatafnEnvelope<T>): T
+
+Helper to unwrap success result or throw error from an envelope.
+
+#### normalizeDfql(dfql: unknown): unknown
+
+```typescript
+import { normalizeDfql } from "@datafn/core";
+
+const normalized = normalizeDfql({ b: 2, a: 1, c: undefined });
+// Returns: { a: 1, b: 2 }
+```
+
+Recursively sorts object keys and removes undefined values for deterministic comparison.
+
+#### dfqlKey(dfql: unknown): string
+
+```typescript
+import { dfqlKey } from "@datafn/core";
+
+const key = dfqlKey({ resource: "user", filters: { id: "user:1" } });
+// Returns: deterministic JSON string for caching
+```
+
+Generates a deterministic cache key from DFQL.
+
+#### ok<T>(result: T): DatafnEnvelope<T>
+#### err(error: DatafnError): DatafnEnvelope<never>
+
+Helpers to create success and error envelopes.
+
+### Error Handling
+
+DatafnError is a plain object interface, not a class.
+
+#### DatafnError
+
+```typescript
+interface DatafnError {
+  code: DatafnErrorCode;
+  message: string;
+  details?: {
+    path: string;
+    [key: string]: unknown;
+  };
+}
+```
+
+The `details.path` property is always present to indicate the location of the error (e.g., `"filters.status"` or `"$"`).
+
+**Example:**
+
+```typescript
+const error: DatafnError = {
+  code: "DFQL_INVALID",
+  message: "Invalid query filter",
+  details: {
+    path: "filters.status",
+    expected: ["active", "archived"]
+  }
+};
+```
+
+## Schema Definition Example
+
+```typescript
+import { DatafnSchema } from "@datafn/core";
+
+const schema: DatafnSchema = {
+  resources: [
+    {
+      name: "post",
+      version: 1,
+      fields: [
+        { name: "title", type: "string", required: true },
+        { name: "content", type: "string", required: true },
+        { name: "authorId", type: "string", required: true },
+        { name: "publishedAt", type: "date", required: false },
+      ],
+      indices: {
+        base: ["authorId"],
+        search: ["title", "content"],
+      },
+    },
+  ],
+  relations: [
+    {
+      from: "post",
+      to: "user",
+      type: "many-one",
+      relation: "author",
+      fkField: "authorId",
+    },
+  ],
+};
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,162 @@
+'use strict';
+
+// src/errors.ts
+function ok(result) {
+  return { ok: true, result };
+}
+function err(code, message, details) {
+  return {
+    ok: false,
+    error: {
+      code,
+      message,
+      details: details ?? { path: "$" }
+    }
+  };
+}
+
+// src/schema.ts
+function validateSchema(schema) {
+  if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+    return err("SCHEMA_INVALID", "Invalid schema: expected object", {
+      path: "$"
+    });
+  }
+  const s = schema;
+  if (!s.resources || !Array.isArray(s.resources)) {
+    return err("SCHEMA_INVALID", "Invalid schema: missing resources", {
+      path: "resources"
+    });
+  }
+  const resourceNames = /* @__PURE__ */ new Set();
+  const normalizedResources = [];
+  for (const resource of s.resources) {
+    if (typeof resource !== "object" || resource === null || Array.isArray(resource)) {
+      return err("SCHEMA_INVALID", "Invalid schema: resource must be object", {
+        path: "resources"
+      });
+    }
+    const r = resource;
+    if (typeof r.name !== "string") {
+      return err(
+        "SCHEMA_INVALID",
+        "Invalid schema: resource.name must be string",
+        { path: "resources" }
+      );
+    }
+    if (resourceNames.has(r.name)) {
+      return err(
+        "SCHEMA_INVALID",
+        `Invalid schema: duplicate resource name: ${r.name}`,
+        { path: "resources" }
+      );
+    }
+    resourceNames.add(r.name);
+    if (typeof r.version !== "number" || !Number.isInteger(r.version)) {
+      return err(
+        "SCHEMA_INVALID",
+        "Invalid schema: resource.version must be integer",
+        { path: "resources" }
+      );
+    }
+    if (!Array.isArray(r.fields)) {
+      return err(
+        "SCHEMA_INVALID",
+        "Invalid schema: resource.fields must be array",
+        { path: "resources" }
+      );
+    }
+    const fieldNames = /* @__PURE__ */ new Set();
+    for (const field of r.fields) {
+      if (typeof field !== "object" || field === null || Array.isArray(field)) {
+        return err("SCHEMA_INVALID", "Invalid schema: field must be object", {
+          path: "resources"
+        });
+      }
+      const f = field;
+      if (typeof f.name !== "string") {
+        return err(
+          "SCHEMA_INVALID",
+          "Invalid schema: field.name must be string",
+          { path: "resources" }
+        );
+      }
+      if (fieldNames.has(f.name)) {
+        return err(
+          "SCHEMA_INVALID",
+          `Invalid schema: duplicate field name: ${f.name}`,
+          { path: "resources" }
+        );
+      }
+      fieldNames.add(f.name);
+    }
+    let normalizedIndices;
+    if (Array.isArray(r.indices)) {
+      normalizedIndices = {
+        base: r.indices,
+        search: [],
+        vector: []
+      };
+    } else if (r.indices && typeof r.indices === "object") {
+      const idx = r.indices;
+      normalizedIndices = {
+        base: idx.base || [],
+        search: idx.search || [],
+        vector: idx.vector || []
+      };
+    } else {
+      normalizedIndices = { base: [], search: [], vector: [] };
+    }
+    normalizedResources.push({
+      ...r,
+      indices: normalizedIndices
+    });
+  }
+  const relations = Array.isArray(s.relations) ? s.relations : [];
+  return ok({
+    resources: normalizedResources,
+    relations
+  });
+}
+
+// src/normalize.ts
+function normalizeDfql(value) {
+  if (value === null || value === void 0) {
+    return value === null ? null : void 0;
+  }
+  if (typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeDfql(item));
+  }
+  const normalized = {};
+  const keys = Object.keys(value).sort();
+  for (const key of keys) {
+    const val = value[key];
+    if (val !== void 0) {
+      normalized[key] = normalizeDfql(val);
+    }
+  }
+  return normalized;
+}
+function dfqlKey(value) {
+  return JSON.stringify(normalizeDfql(value));
+}
+
+// src/envelope.ts
+function unwrapEnvelope(env) {
+  if (env.ok) {
+    return env.result;
+  }
+  throw env.error;
+}
+
+exports.dfqlKey = dfqlKey;
+exports.err = err;
+exports.normalizeDfql = normalizeDfql;
+exports.ok = ok;
+exports.unwrapEnvelope = unwrapEnvelope;
+exports.validateSchema = validateSchema;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/schema.ts","../src/normalize.ts","../src/envelope.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * DataFn Error Types and Envelopes\n */\n\nexport type DatafnErrorCode =\n  | \"SCHEMA_INVALID\"\n  | \"DFQL_INVALID\"\n  | \"DFQL_UNKNOWN_RESOURCE\"\n  | \"DFQL_UNKNOWN_FIELD\"\n  | \"DFQL_UNKNOWN_RELATION\"\n  | \"DFQL_UNSUPPORTED\"\n  | \"LIMIT_EXCEEDED\"\n  | \"FORBIDDEN\"\n  | \"NOT_FOUND\"\n  | \"CONFLICT\"\n  | \"INTERNAL\";\n\nexport type DatafnError = {\n  code: DatafnErrorCode;\n  message: string;\n  details?: unknown;\n};\n\nexport type DatafnEnvelope<T> =\n  | { ok: true; result: T }\n  | { ok: false; error: DatafnError };\n\n/**\n * Helper functions for creating envelopes\n */\n\nexport function ok<T>(result: T): DatafnEnvelope<T> {\n  return { ok: true, result };\n}\n\nexport function err<T = never>(\n  code: DatafnErrorCode,\n  message: string,\n  details?: unknown\n): DatafnEnvelope<T> {\n  return {\n    ok: false,\n    error: {\n      code,\n      message,\n      details: details ?? { path: \"$\" },\n    },\n  };\n}\n","/**\n * Schema Validation\n *\n * Validates and normalizes DataFn schemas according to SCHEMA-001.\n */\n\nimport type { DatafnSchema, DatafnResourceSchema } from \"./types.js\";\nimport type { DatafnEnvelope } from \"./errors.js\";\nimport { ok, err } from \"./errors.js\";\n\n/**\n * Validates a schema and returns a normalized version.\n *\n * Normalization:\n * - Converts `indices: string[]` to `{ base: string[], search: [], vector: [] }`\n * - Ensures `relations` is present (defaults to [])\n *\n * Validation:\n * - `resources` must be present and be an array\n * - Each resource must have unique `name` and integer `version`\n * - Fields must have unique names within a resource\n */\nexport function validateSchema(schema: unknown): DatafnEnvelope<DatafnSchema> {\n  // Check that schema is an object\n  if (typeof schema !== \"object\" || schema === null || Array.isArray(schema)) {\n    return err(\"SCHEMA_INVALID\", \"Invalid schema: expected object\", {\n      path: \"$\",\n    });\n  }\n\n  const s = schema as Record<string, unknown>;\n\n  // Check resources exists and is an array\n  if (!s.resources || !Array.isArray(s.resources)) {\n    return err(\"SCHEMA_INVALID\", \"Invalid schema: missing resources\", {\n      path: \"resources\",\n    });\n  }\n\n  const resourceNames = new Set<string>();\n  const normalizedResources: DatafnResourceSchema[] = [];\n\n  for (const resource of s.resources) {\n    if (\n      typeof resource !== \"object\" ||\n      resource === null ||\n      Array.isArray(resource)\n    ) {\n      return err(\"SCHEMA_INVALID\", \"Invalid schema: resource must be object\", {\n        path: \"resources\",\n      });\n    }\n\n    const r = resource as Record<string, unknown>;\n\n    // Validate name\n    if (typeof r.name !== \"string\") {\n      return err(\n        \"SCHEMA_INVALID\",\n        \"Invalid schema: resource.name must be string\",\n        { path: \"resources\" }\n      );\n    }\n\n    // Check for duplicate resource names\n    if (resourceNames.has(r.name)) {\n      return err(\n        \"SCHEMA_INVALID\",\n        `Invalid schema: duplicate resource name: ${r.name}`,\n        { path: \"resources\" }\n      );\n    }\n    resourceNames.add(r.name);\n\n    // Validate version\n    if (typeof r.version !== \"number\" || !Number.isInteger(r.version)) {\n      return err(\n        \"SCHEMA_INVALID\",\n        \"Invalid schema: resource.version must be integer\",\n        { path: \"resources\" }\n      );\n    }\n\n    // Validate fields\n    if (!Array.isArray(r.fields)) {\n      return err(\n        \"SCHEMA_INVALID\",\n        \"Invalid schema: resource.fields must be array\",\n        { path: \"resources\" }\n      );\n    }\n\n    const fieldNames = new Set<string>();\n    for (const field of r.fields) {\n      if (typeof field !== \"object\" || field === null || Array.isArray(field)) {\n        return err(\"SCHEMA_INVALID\", \"Invalid schema: field must be object\", {\n          path: \"resources\",\n        });\n      }\n      const f = field as Record<string, unknown>;\n      if (typeof f.name !== \"string\") {\n        return err(\n          \"SCHEMA_INVALID\",\n          \"Invalid schema: field.name must be string\",\n          { path: \"resources\" }\n        );\n      }\n      if (fieldNames.has(f.name)) {\n        return err(\n          \"SCHEMA_INVALID\",\n          `Invalid schema: duplicate field name: ${f.name}`,\n          { path: \"resources\" }\n        );\n      }\n      fieldNames.add(f.name);\n    }\n\n    // Normalize indices\n    let normalizedIndices: {\n      base: string[];\n      search: string[];\n      vector: string[];\n    };\n    if (Array.isArray(r.indices)) {\n      normalizedIndices = {\n        base: r.indices as string[],\n        search: [],\n        vector: [],\n      };\n    } else if (r.indices && typeof r.indices === \"object\") {\n      const idx = r.indices as Record<string, unknown>;\n      normalizedIndices = {\n        base: (idx.base as string[]) || [],\n        search: (idx.search as string[]) || [],\n        vector: (idx.vector as string[]) || [],\n      };\n    } else {\n      normalizedIndices = { base: [], search: [], vector: [] };\n    }\n\n    normalizedResources.push({\n      ...r,\n      indices: normalizedIndices,\n    } as DatafnResourceSchema);\n  }\n\n  // Normalize relations (default to empty array)\n  const relations = Array.isArray(s.relations) ? s.relations : [];\n\n  return ok({\n    resources: normalizedResources,\n    relations: relations as DatafnSchema[\"relations\"],\n  });\n}\n","/**\n * DFQL Normalization\n *\n * Produces canonical JSON for DFQL objects to enable stable cache keys\n * and deterministic comparisons.\n */\n\n/**\n * Recursively normalizes a value:\n * - Sorts object keys alphabetically\n * - Removes undefined values\n * - Preserves arrays, primitives, and null as-is\n */\nexport function normalizeDfql(value: unknown): unknown {\n  if (value === null || value === undefined) {\n    return value === null ? null : undefined;\n  }\n\n  if (typeof value !== \"object\") {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map((item) => normalizeDfql(item));\n  }\n\n  // Object: sort keys, remove undefined values, recursively normalize\n  const normalized: Record<string, unknown> = {};\n  const keys = Object.keys(value as Record<string, unknown>).sort();\n\n  for (const key of keys) {\n    const val = (value as Record<string, unknown>)[key];\n    if (val !== undefined) {\n      normalized[key] = normalizeDfql(val);\n    }\n  }\n\n  return normalized;\n}\n\n/**\n * Returns a stable string key for a  DFQL value.\n * This is the canonical form used for caching and comparison.\n */\nexport function dfqlKey(value: unknown): string {\n  return JSON.stringify(normalizeDfql(value));\n}\n","/**\n * DataFn Envelope Utilities\n */\n\nimport type { DatafnEnvelope, DatafnError } from \"./errors.js\";\n\n/**\n * Unwraps a DatafnEnvelope, returning the result for ok:true\n * or throwing the exact error object for ok:false.\n *\n * This provides deterministic error handling for envelope-returning functions.\n *\n * @param env - The envelope to unwrap\n * @returns The result value for success envelopes\n * @throws The exact DatafnError object for failure envelopes\n */\nexport function unwrapEnvelope<T>(env: DatafnEnvelope<T>): T {\n  if (env.ok) {\n    return env.result;\n  }\n  // Throw the exact error object (code/message/details.path match)\n  throw env.error;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,178 @@
+/**
+ * DataFn Schema Types
+ */
+type DatafnSchema = {
+    resources: DatafnResourceSchema[];
+    relations?: DatafnRelationSchema[];
+};
+type DatafnResourceSchema = {
+    name: string;
+    version: number;
+    idPrefix?: string;
+    isRemoteOnly?: boolean;
+    fields: DatafnFieldSchema[];
+    indices?: {
+        base?: string[];
+        search?: string[];
+        vector?: string[];
+    } | string[];
+    permissions?: unknown;
+};
+type DatafnFieldSchema = {
+    name: string;
+    type: "string" | "number" | "boolean" | "object" | "array" | "date" | "file";
+    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";
+    }>;
+    fkField?: string;
+    pathField?: string;
+};
+/**
+ * Event Types
+ */
+interface DatafnEvent {
+    type: "mutation_applied" | "mutation_rejected" | "sync_applied" | "sync_failed";
+    resource?: string;
+    ids?: string[];
+    mutationId?: string;
+    clientId?: string;
+    timestampMs: number;
+    context?: unknown;
+    action?: string;
+    fields?: string[];
+}
+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[];
+}>;
+/**
+ * Signal Type
+ */
+interface DatafnSignal<T> {
+    get(): T;
+    subscribe(handler: (value: T) => void): () => void;
+}
+/**
+ * Plugin Types
+ */
+type DatafnHookContext = {
+    env: "client" | "server";
+    schema: DatafnSchema;
+    context?: unknown;
+};
+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: "seed" | "clone" | "pull" | "push", payload: unknown) => Promise<unknown> | unknown;
+    afterSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push", payload: unknown, result: unknown) => Promise<void> | void;
+}
+
+/**
+ * DataFn Error Types and Envelopes
+ */
+type DatafnErrorCode = "SCHEMA_INVALID" | "DFQL_INVALID" | "DFQL_UNKNOWN_RESOURCE" | "DFQL_UNKNOWN_FIELD" | "DFQL_UNKNOWN_RELATION" | "DFQL_UNSUPPORTED" | "LIMIT_EXCEEDED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL";
+type DatafnError = {
+    code: DatafnErrorCode;
+    message: string;
+    details?: unknown;
+};
+type DatafnEnvelope<T> = {
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    error: DatafnError;
+};
+/**
+ * Helper functions for creating envelopes
+ */
+declare function ok<T>(result: T): DatafnEnvelope<T>;
+declare function err<T = never>(code: DatafnErrorCode, message: string, details?: unknown): DatafnEnvelope<T>;
+
+/**
+ * Schema Validation
+ *
+ * Validates and normalizes DataFn schemas according to SCHEMA-001.
+ */
+
+/**
+ * Validates a schema and returns a normalized version.
+ *
+ * Normalization:
+ * - Converts `indices: string[]` to `{ base: string[], search: [], vector: [] }`
+ * - Ensures `relations` is present (defaults to [])
+ *
+ * Validation:
+ * - `resources` must be present and be an array
+ * - Each resource must have unique `name` and integer `version`
+ * - Fields must have unique names within a resource
+ */
+declare function validateSchema(schema: unknown): DatafnEnvelope<DatafnSchema>;
+
+/**
+ * DFQL Normalization
+ *
+ * Produces canonical JSON for DFQL objects to enable stable cache keys
+ * and deterministic comparisons.
+ */
+/**
+ * Recursively normalizes a value:
+ * - Sorts object keys alphabetically
+ * - Removes undefined values
+ * - Preserves arrays, primitives, and null as-is
+ */
+declare function normalizeDfql(value: unknown): unknown;
+/**
+ * Returns a stable string key for a  DFQL value.
+ * This is the canonical form used for caching and comparison.
+ */
+declare function dfqlKey(value: unknown): string;
+
+/**
+ * DataFn Envelope Utilities
+ */
+
+/**
+ * Unwraps a DatafnEnvelope, returning the result for ok:true
+ * or throwing the exact error object for ok:false.
+ *
+ * This provides deterministic error handling for envelope-returning functions.
+ *
+ * @param env - The envelope to unwrap
+ * @returns The result value for success envelopes
+ * @throws The exact DatafnError object for failure envelopes
+ */
+declare function unwrapEnvelope<T>(env: DatafnEnvelope<T>): T;
+
+export { type DatafnEnvelope, type DatafnError, type DatafnErrorCode, type DatafnEvent, type DatafnEventFilter, type DatafnFieldSchema, type DatafnHookContext, type DatafnPlugin, type DatafnRelationSchema, type DatafnResourceSchema, type DatafnSchema, type DatafnSignal, dfqlKey, err, normalizeDfql, ok, unwrapEnvelope, validateSchema };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+/**
+ * DataFn Schema Types
+ */
+type DatafnSchema = {
+    resources: DatafnResourceSchema[];
+    relations?: DatafnRelationSchema[];
+};
+type DatafnResourceSchema = {
+    name: string;
+    version: number;
+    idPrefix?: string;
+    isRemoteOnly?: boolean;
+    fields: DatafnFieldSchema[];
+    indices?: {
+        base?: string[];
+        search?: string[];
+        vector?: string[];
+    } | string[];
+    permissions?: unknown;
+};
+type DatafnFieldSchema = {
+    name: string;
+    type: "string" | "number" | "boolean" | "object" | "array" | "date" | "file";
+    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";
+    }>;
+    fkField?: string;
+    pathField?: string;
+};
+/**
+ * Event Types
+ */
+interface DatafnEvent {
+    type: "mutation_applied" | "mutation_rejected" | "sync_applied" | "sync_failed";
+    resource?: string;
+    ids?: string[];
+    mutationId?: string;
+    clientId?: string;
+    timestampMs: number;
+    context?: unknown;
+    action?: string;
+    fields?: string[];
+}
+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[];
+}>;
+/**
+ * Signal Type
+ */
+interface DatafnSignal<T> {
+    get(): T;
+    subscribe(handler: (value: T) => void): () => void;
+}
+/**
+ * Plugin Types
+ */
+type DatafnHookContext = {
+    env: "client" | "server";
+    schema: DatafnSchema;
+    context?: unknown;
+};
+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: "seed" | "clone" | "pull" | "push", payload: unknown) => Promise<unknown> | unknown;
+    afterSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push", payload: unknown, result: unknown) => Promise<void> | void;
+}
+
+/**
+ * DataFn Error Types and Envelopes
+ */
+type DatafnErrorCode = "SCHEMA_INVALID" | "DFQL_INVALID" | "DFQL_UNKNOWN_RESOURCE" | "DFQL_UNKNOWN_FIELD" | "DFQL_UNKNOWN_RELATION" | "DFQL_UNSUPPORTED" | "LIMIT_EXCEEDED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL";
+type DatafnError = {
+    code: DatafnErrorCode;
+    message: string;
+    details?: unknown;
+};
+type DatafnEnvelope<T> = {
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    error: DatafnError;
+};
+/**
+ * Helper functions for creating envelopes
+ */
+declare function ok<T>(result: T): DatafnEnvelope<T>;
+declare function err<T = never>(code: DatafnErrorCode, message: string, details?: unknown): DatafnEnvelope<T>;
+
+/**
+ * Schema Validation
+ *
+ * Validates and normalizes DataFn schemas according to SCHEMA-001.
+ */
+
+/**
+ * Validates a schema and returns a normalized version.
+ *
+ * Normalization:
+ * - Converts `indices: string[]` to `{ base: string[], search: [], vector: [] }`
+ * - Ensures `relations` is present (defaults to [])
+ *
+ * Validation:
+ * - `resources` must be present and be an array
+ * - Each resource must have unique `name` and integer `version`
+ * - Fields must have unique names within a resource
+ */
+declare function validateSchema(schema: unknown): DatafnEnvelope<DatafnSchema>;
+
+/**
+ * DFQL Normalization
+ *
+ * Produces canonical JSON for DFQL objects to enable stable cache keys
+ * and deterministic comparisons.
+ */
+/**
+ * Recursively normalizes a value:
+ * - Sorts object keys alphabetically
+ * - Removes undefined values
+ * - Preserves arrays, primitives, and null as-is
+ */
+declare function normalizeDfql(value: unknown): unknown;
+/**
+ * Returns a stable string key for a  DFQL value.
+ * This is the canonical form used for caching and comparison.
+ */
+declare function dfqlKey(value: unknown): string;
+
+/**
+ * DataFn Envelope Utilities
+ */
+
+/**
+ * Unwraps a DatafnEnvelope, returning the result for ok:true
+ * or throwing the exact error object for ok:false.
+ *
+ * This provides deterministic error handling for envelope-returning functions.
+ *
+ * @param env - The envelope to unwrap
+ * @returns The result value for success envelopes
+ * @throws The exact DatafnError object for failure envelopes
+ */
+declare function unwrapEnvelope<T>(env: DatafnEnvelope<T>): T;
+
+export { type DatafnEnvelope, type DatafnError, type DatafnErrorCode, type DatafnEvent, type DatafnEventFilter, type DatafnFieldSchema, type DatafnHookContext, type DatafnPlugin, type DatafnRelationSchema, type DatafnResourceSchema, type DatafnSchema, type DatafnSignal, dfqlKey, err, normalizeDfql, ok, unwrapEnvelope, validateSchema };

package/dist/index.js

@@ -0,0 +1,155 @@
+// src/errors.ts
+function ok(result) {
+  return { ok: true, result };
+}
+function err(code, message, details) {
+  return {
+    ok: false,
+    error: {
+      code,
+      message,
+      details: details ?? { path: "$" }
+    }
+  };
+}
+
+// src/schema.ts
+function validateSchema(schema) {
+  if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+    return err("SCHEMA_INVALID", "Invalid schema: expected object", {
+      path: "$"
+    });
+  }
+  const s = schema;
+  if (!s.resources || !Array.isArray(s.resources)) {
+    return err("SCHEMA_INVALID", "Invalid schema: missing resources", {
+      path: "resources"
+    });
+  }
+  const resourceNames = /* @__PURE__ */ new Set();
+  const normalizedResources = [];
+  for (const resource of s.resources) {
+    if (typeof resource !== "object" || resource === null || Array.isArray(resource)) {
+      return err("SCHEMA_INVALID", "Invalid schema: resource must be object", {
+        path: "resources"
+      });
+    }
+    const r = resource;
+    if (typeof r.name !== "string") {
+      return err(
+        "SCHEMA_INVALID",
+        "Invalid schema: resource.name must be string",
+        { path: "resources" }
+      );
+    }
+    if (resourceNames.has(r.name)) {
+      return err(
+        "SCHEMA_INVALID",
+        `Invalid schema: duplicate resource name: ${r.name}`,
+        { path: "resources" }
+      );
+    }
+    resourceNames.add(r.name);
+    if (typeof r.version !== "number" || !Number.isInteger(r.version)) {
+      return err(
+        "SCHEMA_INVALID",
+        "Invalid schema: resource.version must be integer",
+        { path: "resources" }
+      );
+    }
+    if (!Array.isArray(r.fields)) {
+      return err(
+        "SCHEMA_INVALID",
+        "Invalid schema: resource.fields must be array",
+        { path: "resources" }
+      );
+    }
+    const fieldNames = /* @__PURE__ */ new Set();
+    for (const field of r.fields) {
+      if (typeof field !== "object" || field === null || Array.isArray(field)) {
+        return err("SCHEMA_INVALID", "Invalid schema: field must be object", {
+          path: "resources"
+        });
+      }
+      const f = field;
+      if (typeof f.name !== "string") {
+        return err(
+          "SCHEMA_INVALID",
+          "Invalid schema: field.name must be string",
+          { path: "resources" }
+        );
+      }
+      if (fieldNames.has(f.name)) {
+        return err(
+          "SCHEMA_INVALID",
+          `Invalid schema: duplicate field name: ${f.name}`,
+          { path: "resources" }
+        );
+      }
+      fieldNames.add(f.name);
+    }
+    let normalizedIndices;
+    if (Array.isArray(r.indices)) {
+      normalizedIndices = {
+        base: r.indices,
+        search: [],
+        vector: []
+      };
+    } else if (r.indices && typeof r.indices === "object") {
+      const idx = r.indices;
+      normalizedIndices = {
+        base: idx.base || [],
+        search: idx.search || [],
+        vector: idx.vector || []
+      };
+    } else {
+      normalizedIndices = { base: [], search: [], vector: [] };
+    }
+    normalizedResources.push({
+      ...r,
+      indices: normalizedIndices
+    });
+  }
+  const relations = Array.isArray(s.relations) ? s.relations : [];
+  return ok({
+    resources: normalizedResources,
+    relations
+  });
+}
+
+// src/normalize.ts
+function normalizeDfql(value) {
+  if (value === null || value === void 0) {
+    return value === null ? null : void 0;
+  }
+  if (typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeDfql(item));
+  }
+  const normalized = {};
+  const keys = Object.keys(value).sort();
+  for (const key of keys) {
+    const val = value[key];
+    if (val !== void 0) {
+      normalized[key] = normalizeDfql(val);
+    }
+  }
+  return normalized;
+}
+function dfqlKey(value) {
+  return JSON.stringify(normalizeDfql(value));
+}
+
+// src/envelope.ts
+function unwrapEnvelope(env) {
+  if (env.ok) {
+    return env.result;
+  }
+  throw env.error;
+}
+
+export { dfqlKey, err, normalizeDfql, ok, unwrapEnvelope, validateSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/schema.ts","../src/normalize.ts","../src/envelope.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * DataFn Error Types and Envelopes\n */\n\nexport type DatafnErrorCode =\n  | \"SCHEMA_INVALID\"\n  | \"DFQL_INVALID\"\n  | \"DFQL_UNKNOWN_RESOURCE\"\n  | \"DFQL_UNKNOWN_FIELD\"\n  | \"DFQL_UNKNOWN_RELATION\"\n  | \"DFQL_UNSUPPORTED\"\n  | \"LIMIT_EXCEEDED\"\n  | \"FORBIDDEN\"\n  | \"NOT_FOUND\"\n  | \"CONFLICT\"\n  | \"INTERNAL\";\n\nexport type DatafnError = {\n  code: DatafnErrorCode;\n  message: string;\n  details?: unknown;\n};\n\nexport type DatafnEnvelope<T> =\n  | { ok: true; result: T }\n  | { ok: false; error: DatafnError };\n\n/**\n * Helper functions for creating envelopes\n */\n\nexport function ok<T>(result: T): DatafnEnvelope<T> {\n  return { ok: true, result };\n}\n\nexport function err<T = never>(\n  code: DatafnErrorCode,\n  message: string,\n  details?: unknown\n): DatafnEnvelope<T> {\n  return {\n    ok: false,\n    error: {\n      code,\n      message,\n      details: details ?? { path: \"$\" },\n    },\n  };\n}\n","/**\n * Schema Validation\n *\n * Validates and normalizes DataFn schemas according to SCHEMA-001.\n */\n\nimport type { DatafnSchema, DatafnResourceSchema } from \"./types.js\";\nimport type { DatafnEnvelope } from \"./errors.js\";\nimport { ok, err } from \"./errors.js\";\n\n/**\n * Validates a schema and returns a normalized version.\n *\n * Normalization:\n * - Converts `indices: string[]` to `{ base: string[], search: [], vector: [] }`\n * - Ensures `relations` is present (defaults to [])\n *\n * Validation:\n * - `resources` must be present and be an array\n * - Each resource must have unique `name` and integer `version`\n * - Fields must have unique names within a resource\n */\nexport function validateSchema(schema: unknown): DatafnEnvelope<DatafnSchema> {\n  // Check that schema is an object\n  if (typeof schema !== \"object\" || schema === null || Array.isArray(schema)) {\n    return err(\"SCHEMA_INVALID\", \"Invalid schema: expected object\", {\n      path: \"$\",\n    });\n  }\n\n  const s = schema as Record<string, unknown>;\n\n  // Check resources exists and is an array\n  if (!s.resources || !Array.isArray(s.resources)) {\n    return err(\"SCHEMA_INVALID\", \"Invalid schema: missing resources\", {\n      path: \"resources\",\n    });\n  }\n\n  const resourceNames = new Set<string>();\n  const normalizedResources: DatafnResourceSchema[] = [];\n\n  for (const resource of s.resources) {\n    if (\n      typeof resource !== \"object\" ||\n      resource === null ||\n      Array.isArray(resource)\n    ) {\n      return err(\"SCHEMA_INVALID\", \"Invalid schema: resource must be object\", {\n        path: \"resources\",\n      });\n    }\n\n    const r = resource as Record<string, unknown>;\n\n    // Validate name\n    if (typeof r.name !== \"string\") {\n      return err(\n        \"SCHEMA_INVALID\",\n        \"Invalid schema: resource.name must be string\",\n        { path: \"resources\" }\n      );\n    }\n\n    // Check for duplicate resource names\n    if (resourceNames.has(r.name)) {\n      return err(\n        \"SCHEMA_INVALID\",\n        `Invalid schema: duplicate resource name: ${r.name}`,\n        { path: \"resources\" }\n      );\n    }\n    resourceNames.add(r.name);\n\n    // Validate version\n    if (typeof r.version !== \"number\" || !Number.isInteger(r.version)) {\n      return err(\n        \"SCHEMA_INVALID\",\n        \"Invalid schema: resource.version must be integer\",\n        { path: \"resources\" }\n      );\n    }\n\n    // Validate fields\n    if (!Array.isArray(r.fields)) {\n      return err(\n        \"SCHEMA_INVALID\",\n        \"Invalid schema: resource.fields must be array\",\n        { path: \"resources\" }\n      );\n    }\n\n    const fieldNames = new Set<string>();\n    for (const field of r.fields) {\n      if (typeof field !== \"object\" || field === null || Array.isArray(field)) {\n        return err(\"SCHEMA_INVALID\", \"Invalid schema: field must be object\", {\n          path: \"resources\",\n        });\n      }\n      const f = field as Record<string, unknown>;\n      if (typeof f.name !== \"string\") {\n        return err(\n          \"SCHEMA_INVALID\",\n          \"Invalid schema: field.name must be string\",\n          { path: \"resources\" }\n        );\n      }\n      if (fieldNames.has(f.name)) {\n        return err(\n          \"SCHEMA_INVALID\",\n          `Invalid schema: duplicate field name: ${f.name}`,\n          { path: \"resources\" }\n        );\n      }\n      fieldNames.add(f.name);\n    }\n\n    // Normalize indices\n    let normalizedIndices: {\n      base: string[];\n      search: string[];\n      vector: string[];\n    };\n    if (Array.isArray(r.indices)) {\n      normalizedIndices = {\n        base: r.indices as string[],\n        search: [],\n        vector: [],\n      };\n    } else if (r.indices && typeof r.indices === \"object\") {\n      const idx = r.indices as Record<string, unknown>;\n      normalizedIndices = {\n        base: (idx.base as string[]) || [],\n        search: (idx.search as string[]) || [],\n        vector: (idx.vector as string[]) || [],\n      };\n    } else {\n      normalizedIndices = { base: [], search: [], vector: [] };\n    }\n\n    normalizedResources.push({\n      ...r,\n      indices: normalizedIndices,\n    } as DatafnResourceSchema);\n  }\n\n  // Normalize relations (default to empty array)\n  const relations = Array.isArray(s.relations) ? s.relations : [];\n\n  return ok({\n    resources: normalizedResources,\n    relations: relations as DatafnSchema[\"relations\"],\n  });\n}\n","/**\n * DFQL Normalization\n *\n * Produces canonical JSON for DFQL objects to enable stable cache keys\n * and deterministic comparisons.\n */\n\n/**\n * Recursively normalizes a value:\n * - Sorts object keys alphabetically\n * - Removes undefined values\n * - Preserves arrays, primitives, and null as-is\n */\nexport function normalizeDfql(value: unknown): unknown {\n  if (value === null || value === undefined) {\n    return value === null ? null : undefined;\n  }\n\n  if (typeof value !== \"object\") {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map((item) => normalizeDfql(item));\n  }\n\n  // Object: sort keys, remove undefined values, recursively normalize\n  const normalized: Record<string, unknown> = {};\n  const keys = Object.keys(value as Record<string, unknown>).sort();\n\n  for (const key of keys) {\n    const val = (value as Record<string, unknown>)[key];\n    if (val !== undefined) {\n      normalized[key] = normalizeDfql(val);\n    }\n  }\n\n  return normalized;\n}\n\n/**\n * Returns a stable string key for a  DFQL value.\n * This is the canonical form used for caching and comparison.\n */\nexport function dfqlKey(value: unknown): string {\n  return JSON.stringify(normalizeDfql(value));\n}\n","/**\n * DataFn Envelope Utilities\n */\n\nimport type { DatafnEnvelope, DatafnError } from \"./errors.js\";\n\n/**\n * Unwraps a DatafnEnvelope, returning the result for ok:true\n * or throwing the exact error object for ok:false.\n *\n * This provides deterministic error handling for envelope-returning functions.\n *\n * @param env - The envelope to unwrap\n * @returns The result value for success envelopes\n * @throws The exact DatafnError object for failure envelopes\n */\nexport function unwrapEnvelope<T>(env: DatafnEnvelope<T>): T {\n  if (env.ok) {\n    return env.result;\n  }\n  // Throw the exact error object (code/message/details.path match)\n  throw env.error;\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@datafn/core",
+  "version": "0.0.1",
+  "description": "Core types and utilities for datafn - schema validation, DFQL normalization, and shared types",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "keywords": [
+    "datafn",
+    "schema",
+    "validation",
+    "dfql"
+  ],
+  "author": "21n",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/21nCo/super-functions.git",
+    "directory": "datafn/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "bugs": {
+    "url": "https://github.com/21nCo/super-functions/issues"
+  },
+  "superfunctions": {
+    "initFunction": "dataFn",
+    "schemaVersion": 1,
+    "namespace": "datafn"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}