barkql 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 eli0shin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# barkql
+
+Type-safe query builder with compile-time validation. Build complex queries with operators and get helpful error messages when the structure is invalid.
+
+## Why?
+
+Query strings are hard to work with:
+
+- Long strings lack syntax highlighting and can't be formatted
+- Errors are invisible until runtime
+- Easy to put two operators next to each other or forget one
+
+This library lets you build queries as structured data with compile-time validation.
+
+## Installation
+
+```bash
+bun add barkql
+```
+
+## Quick Start
+
+```typescript
+import { query, compileDatadogQuery } from 'barkql';
+
+// Build a query with compile-time validation
+const q = query([{ service: 'api' }, 'AND', { env: 'production' }]);
+
+// Compile to Datadog query string
+const str = compileDatadogQuery(q);
+// '(service:"api" AND env:"production")'
+```
+
+## Usage
+
+### Simple query
+
+```typescript
+query([{ name: 'John' }]);
+```
+
+### Query with operators
+
+```typescript
+query([{ name: 'John' }, 'AND', { age: 30 }]);
+query([{ status: 'active' }, 'OR', { role: 'admin' }]);
+query([{ env: 'prod' }, 'AND NOT', { service: 'debug' }]);
+```
+
+### Nested queries
+
+```typescript
+query([[{ name: 'John' }, 'OR', { name: 'Jane' }], 'AND', { age: 30 }]);
+
+query([
+  [{ country: 'USA' }, 'OR', { country: 'Canada' }],
+  'AND',
+  [{ age: 25 }, 'OR', { experience: 5 }],
+]);
+```
+
+### Query builder
+
+```typescript
+import { queryBuilder } from 'barkql';
+
+const q = queryBuilder({ name: 'John' })
+  .and({ age: 30 })
+  .or({ active: true })
+  .build();
+```
+
+### Compile to Datadog format
+
+```typescript
+import { compileDatadogQuery } from 'barkql';
+
+compileDatadogQuery({ name: 'John', age: 30 });
+// 'name:"John" AND age:30'
+
+compileDatadogQuery([{ a: 1 }, 'AND', { b: 2 }]);
+// '(a:1 AND b:2)'
+
+compileDatadogQuery({ tags: ['error', 'warning'] });
+// 'tags:("error" OR "warning")'
+```
+
+## Query Syntax
+
+- **Operators**: `'AND' | 'OR' | 'AND NOT' | 'OR NOT'`
+- **Values**: `string | number | boolean | null | Array<string | number | boolean | null>`
+- **Pattern**: `[Query]` or `[Query, Operator, Query, ...]`
+- **Nesting**: Any query position accepts a nested query chain
+- **Arrays**: Compiled as `(value1 OR value2 OR ...)`
+
+## API
+
+### `query(input)`
+
+Creates a type-safe query. Returns the input unchanged but validates the structure at compile time.
+
+### `queryBuilder(initialQuery)`
+
+Fluent builder with `.and()`, `.or()`, `.andNot()`, `.orNot()` methods. Call `.build()` to get the query.
+
+### `compileDatadogQuery(query)`
+
+Compiles a query to Datadog query string format.

package/dist/index.cjs

@@ -0,0 +1,105 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  queryBuilder: () => queryBuilder,
+  query: () => query,
+  compileDatadogQuery: () => compileDatadogQuery
+});
+module.exports = __toCommonJS(exports_src);
+function query(query2) {
+  return query2;
+}
+function formatValue(value) {
+  if (typeof value === "string") {
+    return `"${value}"`;
+  }
+  return String(value);
+}
+function formatArrayValue(values) {
+  return `(${values.map(formatValue).join(" OR ")})`;
+}
+function isQueryChain(value) {
+  return Array.isArray(value);
+}
+function isOperator(value) {
+  return value === "AND" || value === "OR" || value === "AND NOT" || value === "OR NOT";
+}
+function compileBaseQuery(query2) {
+  const entries = Object.entries(query2);
+  if (entries.length === 0)
+    return "";
+  return entries.map(([key, value]) => {
+    if (Array.isArray(value)) {
+      return `${key}:${formatArrayValue(value)}`;
+    }
+    return `${key}:${formatValue(value)}`;
+  }).join(" AND ");
+}
+function compileDatadogQuery(query2) {
+  if (isQueryChain(query2)) {
+    const parts = [];
+    for (const element of query2) {
+      if (isOperator(element)) {
+        parts.push(element);
+      } else if (isQueryChain(element)) {
+        parts.push(compileDatadogQuery(element));
+      } else {
+        parts.push(compileBaseQuery(element));
+      }
+    }
+    return `(${parts.join(" ")})`;
+  }
+  return compileBaseQuery(query2);
+}
+function queryBuilder(initialQuery) {
+  const wrapIfNeeded = (q) => Array.isArray(q) ? q : [q];
+  const queries = [wrapIfNeeded(initialQuery)];
+  const builder = {
+    build: () => [...queries],
+    and: (query2) => {
+      queries.push("AND", wrapIfNeeded(query2));
+      return builder;
+    },
+    or: (query2) => {
+      queries.push("OR", wrapIfNeeded(query2));
+      return builder;
+    },
+    andNot: (query2) => {
+      queries.push("AND NOT", wrapIfNeeded(query2));
+      return builder;
+    },
+    orNot: (query2) => {
+      queries.push("OR NOT", wrapIfNeeded(query2));
+      return builder;
+    }
+  };
+  return builder;
+}

package/dist/index.d.cts

@@ -0,0 +1,54 @@
+export type Operator = 'AND' | 'OR' | 'AND NOT' | 'OR NOT';
+export type QueryValue = string | null | boolean | number;
+export type BaseQueryType = Record<string, QueryValue | QueryValue[] | readonly QueryValue[]>;
+export type QueryChain<T extends readonly unknown[] = readonly unknown[]> = ValidatePattern<T>;
+export type Query = BaseQueryType | QueryChain;
+type ValidatedQueryInput<Q> = Q extends readonly unknown[] ? Q & ValidatePattern<Q> : Q extends BaseQueryType ? Q : never;
+type IsValidQuery<T> = T extends BaseQueryType ? true : T extends readonly unknown[] ? ValidatePatternWithError<T> extends 'valid' ? true : false : false;
+export type ValidatePatternWithError<T extends readonly unknown[]> = T extends readonly [] ? 'ERROR: Query cannot be empty. Expected: [Query] or [Query, Operator, Query, ...]' : T extends readonly [infer First, ...infer Rest] ? IsValidQuery<First> extends true ? Rest extends readonly [] ? 'valid' : Rest extends readonly [infer Op, ...infer After] ? Op extends Operator ? After extends readonly [] ? 'ERROR: Query cannot end with an Operator. Expected a Query after the Operator.' : After extends readonly [infer Next, ...infer RestAfter] ? IsValidQuery<Next> extends true ? ValidatePatternWithError<readonly [Next, ...RestAfter]> : 'ERROR: After an Operator, expected a Query (BaseQueryType or nested QueryChain) but found something else.' : 'ERROR: Invalid pattern structure. Expected: Query, Operator, Query, ...' : "ERROR: After a Query, expected an Operator ('AND' | 'OR' | 'AND NOT' | 'OR NOT') but found something else." : 'ERROR: Invalid pattern structure. After Query, expected an Operator followed by another Query.' : First extends Operator ? 'ERROR: Query cannot start with an Operator. It must start with a Query.' : 'ERROR: Query must start with a Query (BaseQueryType or nested QueryChain).' : 'ERROR: Invalid query pattern.';
+export type ValidatePattern<T extends readonly unknown[]> = ValidatePatternWithError<T> extends 'valid' ? T : ValidatePatternWithError<T>;
+/**
+ * Creates a type-safe query with compile-time validation.
+ *
+ * @example
+ * query([{ name: 'John' }])
+ * query([{ name: 'John' }, 'AND', { age: 30 }])
+ * query([[{ a: 1 }, 'OR', { b: 2 }], 'AND', { c: 3 }])
+ */
+export declare function query<const T extends readonly unknown[]>(query: T & ValidatePattern<T>): T;
+type QueryBuilder<T extends readonly unknown[] = []> = {
+    build: () => ValidatePattern<T>;
+    and: <Q extends BaseQueryType | readonly unknown[]>(query: ValidatedQueryInput<Q>) => QueryBuilder<readonly [...T, 'AND', Q extends readonly unknown[] ? Q : readonly [Q]]>;
+    or: <Q extends BaseQueryType | readonly unknown[]>(query: ValidatedQueryInput<Q>) => QueryBuilder<readonly [...T, 'OR', Q extends readonly unknown[] ? Q : readonly [Q]]>;
+    andNot: <Q extends BaseQueryType | readonly unknown[]>(query: ValidatedQueryInput<Q>) => QueryBuilder<readonly [...T, 'AND NOT', Q extends readonly unknown[] ? Q : readonly [Q]]>;
+    orNot: <Q extends BaseQueryType | readonly unknown[]>(query: ValidatedQueryInput<Q>) => QueryBuilder<readonly [...T, 'OR NOT', Q extends readonly unknown[] ? Q : readonly [Q]]>;
+};
+/**
+ * Compiles a query to Datadog query string format.
+ *
+ * @example
+ * compileDatadogQuery({ name: 'John', age: 30 })
+ * // Returns: 'name:"John" AND age:30'
+ *
+ * compileDatadogQuery([{ a: 1 }, 'AND', { b: 2 }])
+ * // Returns: '(a:1 AND b:2)'
+ */
+export declare function compileDatadogQuery(query: BaseQueryType): string;
+export declare function compileDatadogQuery<const T extends readonly unknown[]>(query: T & ValidatePattern<T>): string;
+/**
+ * Fluent builder for constructing queries with method chaining.
+ *
+ * @example
+ * queryBuilder({ name: 'John' })
+ *   .and({ age: 30 })
+ *   .or({ active: true })
+ *   .build()
+ *
+ * @example
+ * queryBuilder([{ a: 1 }, 'OR', { b: 2 }] as const)
+ *   .and({ c: 3 })
+ *   .build()
+ */
+export declare function queryBuilder<Q extends BaseQueryType>(initialQuery: Q): QueryBuilder<readonly [readonly [Q]]>;
+export declare function queryBuilder<const T extends readonly unknown[]>(initialQuery: T & ValidatePattern<T>): QueryBuilder<readonly [T]>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+export type Operator = 'AND' | 'OR' | 'AND NOT' | 'OR NOT';
+export type QueryValue = string | null | boolean | number;
+export type BaseQueryType = Record<string, QueryValue | QueryValue[] | readonly QueryValue[]>;
+export type QueryChain<T extends readonly unknown[] = readonly unknown[]> = ValidatePattern<T>;
+export type Query = BaseQueryType | QueryChain;
+type ValidatedQueryInput<Q> = Q extends readonly unknown[] ? Q & ValidatePattern<Q> : Q extends BaseQueryType ? Q : never;
+type IsValidQuery<T> = T extends BaseQueryType ? true : T extends readonly unknown[] ? ValidatePatternWithError<T> extends 'valid' ? true : false : false;
+export type ValidatePatternWithError<T extends readonly unknown[]> = T extends readonly [] ? 'ERROR: Query cannot be empty. Expected: [Query] or [Query, Operator, Query, ...]' : T extends readonly [infer First, ...infer Rest] ? IsValidQuery<First> extends true ? Rest extends readonly [] ? 'valid' : Rest extends readonly [infer Op, ...infer After] ? Op extends Operator ? After extends readonly [] ? 'ERROR: Query cannot end with an Operator. Expected a Query after the Operator.' : After extends readonly [infer Next, ...infer RestAfter] ? IsValidQuery<Next> extends true ? ValidatePatternWithError<readonly [Next, ...RestAfter]> : 'ERROR: After an Operator, expected a Query (BaseQueryType or nested QueryChain) but found something else.' : 'ERROR: Invalid pattern structure. Expected: Query, Operator, Query, ...' : "ERROR: After a Query, expected an Operator ('AND' | 'OR' | 'AND NOT' | 'OR NOT') but found something else." : 'ERROR: Invalid pattern structure. After Query, expected an Operator followed by another Query.' : First extends Operator ? 'ERROR: Query cannot start with an Operator. It must start with a Query.' : 'ERROR: Query must start with a Query (BaseQueryType or nested QueryChain).' : 'ERROR: Invalid query pattern.';
+export type ValidatePattern<T extends readonly unknown[]> = ValidatePatternWithError<T> extends 'valid' ? T : ValidatePatternWithError<T>;
+/**
+ * Creates a type-safe query with compile-time validation.
+ *
+ * @example
+ * query([{ name: 'John' }])
+ * query([{ name: 'John' }, 'AND', { age: 30 }])
+ * query([[{ a: 1 }, 'OR', { b: 2 }], 'AND', { c: 3 }])
+ */
+export declare function query<const T extends readonly unknown[]>(query: T & ValidatePattern<T>): T;
+type QueryBuilder<T extends readonly unknown[] = []> = {
+    build: () => ValidatePattern<T>;
+    and: <Q extends BaseQueryType | readonly unknown[]>(query: ValidatedQueryInput<Q>) => QueryBuilder<readonly [...T, 'AND', Q extends readonly unknown[] ? Q : readonly [Q]]>;
+    or: <Q extends BaseQueryType | readonly unknown[]>(query: ValidatedQueryInput<Q>) => QueryBuilder<readonly [...T, 'OR', Q extends readonly unknown[] ? Q : readonly [Q]]>;
+    andNot: <Q extends BaseQueryType | readonly unknown[]>(query: ValidatedQueryInput<Q>) => QueryBuilder<readonly [...T, 'AND NOT', Q extends readonly unknown[] ? Q : readonly [Q]]>;
+    orNot: <Q extends BaseQueryType | readonly unknown[]>(query: ValidatedQueryInput<Q>) => QueryBuilder<readonly [...T, 'OR NOT', Q extends readonly unknown[] ? Q : readonly [Q]]>;
+};
+/**
+ * Compiles a query to Datadog query string format.
+ *
+ * @example
+ * compileDatadogQuery({ name: 'John', age: 30 })
+ * // Returns: 'name:"John" AND age:30'
+ *
+ * compileDatadogQuery([{ a: 1 }, 'AND', { b: 2 }])
+ * // Returns: '(a:1 AND b:2)'
+ */
+export declare function compileDatadogQuery(query: BaseQueryType): string;
+export declare function compileDatadogQuery<const T extends readonly unknown[]>(query: T & ValidatePattern<T>): string;
+/**
+ * Fluent builder for constructing queries with method chaining.
+ *
+ * @example
+ * queryBuilder({ name: 'John' })
+ *   .and({ age: 30 })
+ *   .or({ active: true })
+ *   .build()
+ *
+ * @example
+ * queryBuilder([{ a: 1 }, 'OR', { b: 2 }] as const)
+ *   .and({ c: 3 })
+ *   .build()
+ */
+export declare function queryBuilder<Q extends BaseQueryType>(initialQuery: Q): QueryBuilder<readonly [readonly [Q]]>;
+export declare function queryBuilder<const T extends readonly unknown[]>(initialQuery: T & ValidatePattern<T>): QueryBuilder<readonly [T]>;
+export {};

package/dist/index.js

@@ -0,0 +1,75 @@
+// src/index.ts
+function query(query2) {
+  return query2;
+}
+function formatValue(value) {
+  if (typeof value === "string") {
+    return `"${value}"`;
+  }
+  return String(value);
+}
+function formatArrayValue(values) {
+  return `(${values.map(formatValue).join(" OR ")})`;
+}
+function isQueryChain(value) {
+  return Array.isArray(value);
+}
+function isOperator(value) {
+  return value === "AND" || value === "OR" || value === "AND NOT" || value === "OR NOT";
+}
+function compileBaseQuery(query2) {
+  const entries = Object.entries(query2);
+  if (entries.length === 0)
+    return "";
+  return entries.map(([key, value]) => {
+    if (Array.isArray(value)) {
+      return `${key}:${formatArrayValue(value)}`;
+    }
+    return `${key}:${formatValue(value)}`;
+  }).join(" AND ");
+}
+function compileDatadogQuery(query2) {
+  if (isQueryChain(query2)) {
+    const parts = [];
+    for (const element of query2) {
+      if (isOperator(element)) {
+        parts.push(element);
+      } else if (isQueryChain(element)) {
+        parts.push(compileDatadogQuery(element));
+      } else {
+        parts.push(compileBaseQuery(element));
+      }
+    }
+    return `(${parts.join(" ")})`;
+  }
+  return compileBaseQuery(query2);
+}
+function queryBuilder(initialQuery) {
+  const wrapIfNeeded = (q) => Array.isArray(q) ? q : [q];
+  const queries = [wrapIfNeeded(initialQuery)];
+  const builder = {
+    build: () => [...queries],
+    and: (query2) => {
+      queries.push("AND", wrapIfNeeded(query2));
+      return builder;
+    },
+    or: (query2) => {
+      queries.push("OR", wrapIfNeeded(query2));
+      return builder;
+    },
+    andNot: (query2) => {
+      queries.push("AND NOT", wrapIfNeeded(query2));
+      return builder;
+    },
+    orNot: (query2) => {
+      queries.push("OR NOT", wrapIfNeeded(query2));
+      return builder;
+    }
+  };
+  return builder;
+}
+export {
+  queryBuilder,
+  query,
+  compileDatadogQuery
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "barkql",
+  "version": "0.1.1",
+  "description": "Type-safe query builder for Datadog metrics",
+  "license": "MIT",
+  "author": "eli0shin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eli0shin/barkql.git"
+  },
+  "homepage": "https://github.com/eli0shin/barkql#readme",
+  "bugs": {
+    "url": "https://github.com/eli0shin/barkql/issues"
+  },
+  "keywords": [
+    "datadog",
+    "query",
+    "metrics",
+    "typescript",
+    "type-safe"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run build:esm && bun run build:cjs && bun run build:types",
+    "build:esm": "bun build src/index.ts --outdir dist --format esm --target node",
+    "build:cjs": "bun build src/index.ts --outfile dist/index.cjs --format cjs --target node",
+    "build:types": "tsc --project tsconfig.build.json && cp dist/index.d.ts dist/index.d.cts",
+    "test": "vitest run",
+    "test:types": "vitest --typecheck",
+    "type:check": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.7",
+    "@types/bun": "latest",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.6.2",
+    "vitest": "^4.0.13"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,json,md,yml,yaml}": "prettier --write"
+  }
+}