@typicalday/firegraph 0.1.0

package/dist/views-DL60k0cf.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Model Views — framework-agnostic view definitions for graph entities.
+ *
+ * Projects define Web Components that render entity data in purpose-driven
+ * ways. Each view class declares a static `viewName`, and receives the
+ * entity's `data` payload via a `data` property setter.
+ *
+ * @example
+ * ```ts
+ * import { defineViews } from 'firegraph';
+ *
+ * class UserCard extends HTMLElement {
+ *   static viewName = 'card';
+ *   static description = 'Compact user card';
+ *   private _data: Record<string, unknown> = {};
+ *   set data(v: Record<string, unknown>) { this._data = v; this.render(); }
+ *   connectedCallback() { this.render(); }
+ *   private render() {
+ *     this.innerHTML = `<strong>${this._data.displayName ?? ''}</strong>`;
+ *   }
+ * }
+ *
+ * export default defineViews({
+ *   nodes: { user: { views: [UserCard] } },
+ * });
+ * ```
+ */
+/**
+ * A Web Component class used as a view. The class must have a static
+ * `viewName` and must be constructable. It will be registered as a custom
+ * element via `customElements.define()` in browser environments.
+ *
+ * Note: this interface avoids referencing `HTMLElement` directly so the
+ * library can compile without DOM lib types. Consumer code (which has DOM)
+ * will satisfy this constraint naturally.
+ */
+interface ViewComponentClass {
+    new (...args: any[]): {
+        data: Record<string, unknown>;
+    };
+    /** Short identifier for this view (e.g. 'card', 'profile'). */
+    viewName: string;
+    /** Optional human-readable description. */
+    description?: string;
+}
+/** Configuration for all views of a single entity type. */
+interface EntityViewConfig {
+    /** View component classes to register. */
+    views: ViewComponentClass[];
+    /**
+     * Optional sample data for the gallery. A single object matching
+     * the entity's JSON Schema — shared across all views.
+     */
+    sampleData?: Record<string, unknown>;
+}
+/** Input shape accepted by `defineViews()`. */
+interface ViewRegistryInput {
+    /** Node views keyed by aType (e.g. 'user', 'tour'). */
+    nodes?: Record<string, EntityViewConfig>;
+    /** Edge views keyed by axbType (e.g. 'hasDeparture'). */
+    edges?: Record<string, EntityViewConfig>;
+}
+/** Serialisable metadata for a single view. */
+interface ViewMeta {
+    /** Custom element tag name (e.g. 'fg-user-card'). */
+    tagName: string;
+    /** Short identifier matching the component's static viewName. */
+    viewName: string;
+    /** Optional human-readable description. */
+    description?: string;
+}
+/** Serialisable metadata for all views of a single entity type. */
+interface EntityViewMeta {
+    views: ViewMeta[];
+    sampleData?: Record<string, unknown>;
+}
+/** The resolved view registry returned by `defineViews()`. */
+interface ViewRegistry {
+    nodes: Record<string, EntityViewMeta>;
+    edges: Record<string, EntityViewMeta>;
+}
+/**
+ * Build a `ViewRegistry` from component classes.
+ *
+ * In the browser the components are registered as custom elements with
+ * deterministic tag names (`fg-{entityType}-{viewName}`). On the server
+ * (Node.js) only metadata is returned — no custom element registration.
+ */
+declare function defineViews(input: ViewRegistryInput): ViewRegistry;
+
+export { type EntityViewConfig as E, type ViewComponentClass as V, type EntityViewMeta as a, type ViewMeta as b, type ViewRegistry as c, type ViewRegistryInput as d, defineViews as e };

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "@typicalday/firegraph",
+  "version": "0.1.0",
+  "description": "Generic Firestore adjacency graph client with smart query planning",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    },
+    "./svelte": {
+      "import": {
+        "types": "./dist/svelte.d.ts",
+        "default": "./dist/svelte.js"
+      },
+      "require": {
+        "types": "./dist/svelte.d.cts",
+        "default": "./dist/svelte.cjs"
+      }
+    },
+    "./query-client": {
+      "import": {
+        "types": "./dist/query-client/index.d.ts",
+        "default": "./dist/query-client/index.js"
+      },
+      "require": {
+        "types": "./dist/query-client/index.d.cts",
+        "default": "./dist/query-client/index.cjs"
+      }
+    }
+  },
+  "bin": {
+    "firegraph": "./bin/firegraph.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "skills"
+  ],
+  "peerDependencies": {
+    "@google-cloud/firestore": "^8.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "svelte": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "ajv": "^8.18.0",
+    "esbuild": "^0.24.0",
+    "jiti": "^2.4.0",
+    "nanoid": "^5.0.9"
+  },
+  "devDependencies": {
+    "@google-cloud/firestore": "^8.3.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "json-schema-to-typescript": "^15.0.4",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/typicalday/firegraph.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:editor:client": "cd editor && npx vite build",
+    "build:editor:server": "node editor/build-server.mjs",
+    "build:editor": "npm run build:editor:client && npm run build:editor:server",
+    "build:all": "npm run build && npm run build:editor",
+    "dev:editor": "cd editor && npm run dev",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit/",
+    "test:integration": "vitest run tests/integration/",
+    "test:emulator": "bash tests/scripts/test-with-emulator.sh",
+    "test:emulator:unit": "bash tests/scripts/test-with-emulator.sh tests/unit/",
+    "test:emulator:integration": "bash tests/scripts/test-with-emulator.sh tests/integration/",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "emulator:start": "cd tests/emulator && firebase emulators:start -P demo-firegraph",
+    "emulator:stop": "npx kill-port -y 4188 8188",
+    "test:pipeline": "vitest run tests/pipeline/ --config tests/pipeline/vitest.config.ts",
+    "test:pipeline:integration": "vitest run --config tests/integration-pipeline/vitest.config.ts"
+  }
+}