@d-dash/datasource-grpc 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# @d-dash/datasource-grpc
+
+gRPC-backed `DatasourceAdapter` for d-dash.
+
+## Usage
+
+```ts
+import { createGrpcDatasourceAdapter } from "@d-dash/datasource-grpc";
+
+const adapter = createGrpcDatasourceAdapter({
+  id: "grpc",
+  client: {
+    async query(request, context) {
+      // Map request to protobuf call, then map response envelope.
+      return { status: "success", frames: [] };
+    },
+  },
+});
+
+registry.registerDatasource(adapter);
+```
+
+## Client contract
+
+Your injected `client` handles transport specifics and returns a normalized envelope:
+
+- `query(request, context)` is required
+- `getMetrics()` is optional and enables metadata discovery
+
+The adapter normalizes frame payloads to d-dash `DataFrame[]` and maps gRPC
+transport and response failures into structured datasource errors.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import type { DatasourceAdapter, RuntimeContext, VisualizationKind } from "@d-dash/core";
+/** Wire-format query envelope forwarded to gRPC datasource backends. */
+export type GrpcQueryEnvelope = {
+    metric: string;
+    from: number;
+    to: number;
+    filters?: Record<string, unknown>;
+    context?: {
+        traceId?: string;
+    };
+};
+/** Wire-format field returned by gRPC datasource backends. */
+export type GrpcField = {
+    name: string;
+    type: "time" | "number" | "string" | "boolean";
+    values: (string | number | boolean | null)[];
+    labels?: Record<string, string>;
+};
+/** Wire-format frame returned by gRPC datasource backends. */
+export type GrpcFrame = {
+    fields: GrpcField[];
+};
+/** Wire-format top-level response envelope returned by gRPC datasource backends. */
+export type GrpcResponseEnvelope = {
+    status: "success" | "partial" | "error";
+    frames: GrpcFrame[];
+    warnings?: string[];
+    error?: {
+        code?: string;
+        message?: string;
+        retriable?: boolean;
+    };
+};
+/** Wire-format metric definition shape returned by optional discovery APIs. */
+export type GrpcMetricWire = string | {
+    id?: string;
+    name?: string;
+    unit?: string;
+    supportedVisualizations?: VisualizationKind[];
+};
+/** Transport client contract injected into the gRPC datasource adapter. */
+export type GrpcDatasourceClient = {
+    /** Execute a datasource query over gRPC and return normalized wire envelope. */
+    query(request: GrpcQueryEnvelope, context: RuntimeContext): Promise<GrpcResponseEnvelope>;
+    /** Optionally discover supported metrics from backend metadata services. */
+    getMetrics?(): Promise<GrpcMetricWire[]>;
+};
+/** Configuration options for creating the gRPC datasource adapter. */
+export type GrpcDatasourceAdapterOptions = {
+    id: string;
+    client: GrpcDatasourceClient;
+};
+/** Creates a d-dash datasource adapter backed by an injected gRPC client. */
+export declare function createGrpcDatasourceAdapter(options: GrpcDatasourceAdapterOptions): DatasourceAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,iBAAiB,EAMjB,cAAc,EACd,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAEtB,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC/C,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACxC,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GACtB,MAAM,GACN;IACE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uBAAuB,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC/C,CAAC;AAEN,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG;IACjC,gFAAgF;IAChF,KAAK,CACH,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC,4EAA4E;IAC5E,UAAU,CAAC,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CAC1C,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,4BAA4B,GAAG;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,oBAAoB,CAAC;CAC9B,CAAC;AAqFF,6EAA6E;AAC7E,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,4BAA4B,GACpC,iBAAiB,CAuGnB"}

package/dist/index.js

@@ -0,0 +1,155 @@
+const DEFAULT_VISUALIZATIONS = [
+    "timeseries",
+    "stat",
+    "table",
+    "text",
+    "html",
+];
+function normalizeFrames(rawFrames) {
+    return rawFrames.map((frame) => ({
+        fields: frame.fields.map((field) => ({
+            name: field.name,
+            type: field.type,
+            values: field.values,
+            ...(field.labels ? { labels: field.labels } : {}),
+        })),
+    }));
+}
+function toMetricDefinition(metric, datasourceId) {
+    if (typeof metric === "string") {
+        return {
+            id: metric,
+            name: metric,
+            unit: "",
+            datasource: datasourceId,
+            supportedVisualizations: DEFAULT_VISUALIZATIONS,
+        };
+    }
+    const id = metric.id ?? metric.name ?? "";
+    return {
+        id,
+        name: metric.name ?? id,
+        unit: metric.unit ?? "",
+        datasource: datasourceId,
+        supportedVisualizations: metric.supportedVisualizations ?? DEFAULT_VISUALIZATIONS,
+    };
+}
+function isRetriableGrpcCode(code) {
+    if (!code) {
+        return false;
+    }
+    return (code === "UNAVAILABLE" ||
+        code === "DEADLINE_EXCEEDED" ||
+        code === "RESOURCE_EXHAUSTED" ||
+        code === "ABORTED" ||
+        code === "INTERNAL");
+}
+function mapTransportError(error, datasourceId) {
+    const maybe = error;
+    const code = typeof maybe.code === "string" ? maybe.code : undefined;
+    const message = typeof maybe.message === "string" ? maybe.message : undefined;
+    return {
+        status: "error",
+        frames: [],
+        error: {
+            code: "DATASOURCE_QUERY_FAILED",
+            message: message ??
+                `gRPC transport error querying datasource '${datasourceId}'.`,
+            retriable: isRetriableGrpcCode(code),
+            details: code ? { grpcCode: code } : undefined,
+        },
+    };
+}
+const BASE_CAPABILITIES = {
+    supportsAdHocFilters: true,
+};
+/** Creates a d-dash datasource adapter backed by an injected gRPC client. */
+export function createGrpcDatasourceAdapter(options) {
+    const capabilities = {
+        ...BASE_CAPABILITIES,
+        ...(options.client.getMetrics ? { supportsMetadataDiscovery: true } : {}),
+    };
+    return {
+        id: options.id,
+        capabilities,
+        async getMetrics() {
+            if (!options.client.getMetrics) {
+                return [];
+            }
+            try {
+                const raw = await options.client.getMetrics();
+                const metrics = [];
+                for (const item of raw) {
+                    const metric = toMetricDefinition(item, options.id);
+                    if (metric.id.trim().length === 0) {
+                        continue;
+                    }
+                    metrics.push(metric);
+                }
+                return metrics;
+            }
+            catch {
+                return [];
+            }
+        },
+        async query(request, context) {
+            const envelope = {
+                metric: request.metric,
+                from: request.timeRange.from,
+                to: request.timeRange.to,
+                ...(request.filters
+                    ? { filters: request.filters }
+                    : {}),
+                context: {
+                    traceId: context.traceId,
+                },
+            };
+            let response;
+            try {
+                response = await options.client.query(envelope, context);
+            }
+            catch (error) {
+                return mapTransportError(error, options.id);
+            }
+            const frames = normalizeFrames(response.frames ?? []);
+            if (response.status === "error") {
+                return {
+                    status: "error",
+                    frames,
+                    warnings: response.warnings,
+                    error: {
+                        code: (response.error?.code ??
+                            "DATASOURCE_QUERY_FAILED"),
+                        message: response.error?.message ??
+                            "Datasource returned a gRPC error response.",
+                        retriable: typeof response.error?.retriable === "boolean"
+                            ? response.error.retriable
+                            : isRetriableGrpcCode(response.error?.code),
+                    },
+                };
+            }
+            if (response.status === "partial") {
+                return {
+                    status: "partial",
+                    frames,
+                    warnings: response.warnings,
+                    error: {
+                        code: (response.error?.code ??
+                            "DATASOURCE_PARTIAL"),
+                        message: response.error?.message ??
+                            "Datasource returned a partial gRPC response.",
+                        retriable: typeof response.error?.retriable === "boolean"
+                            ? response.error.retriable
+                            : isRetriableGrpcCode(response.error?.code),
+                    },
+                };
+            }
+            return {
+                status: "success",
+                frames,
+                warnings: response.warnings,
+            };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@d-dash/datasource-grpc",
+  "version": "0.1.0",
+  "description": "gRPC datasource adapter for d-dash",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thienvu18/d-dash.git",
+    "directory": "packages/datasource-grpc"
+  },
+  "bugs": {
+    "url": "https://github.com/thienvu18/d-dash/issues"
+  },
+  "homepage": "https://github.com/thienvu18/d-dash/tree/main/packages/datasource-grpc#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test $(find tests -name '*.spec.js')"
+  },
+  "peerDependencies": {
+    "@d-dash/core": "^0.1.0"
+  },
+  "keywords": [
+    "dashboard",
+    "datasource",
+    "grpc",
+    "d-dash"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@d-dash/core": "file:../core",
+    "typescript": "^5.9.3"
+  }
+}