@plumile/filter-query 0.1.32 → 0.1.34

package/src/index.ts

@@ -1,6 +0,0 @@
-export type * from './types.js';
-export * from './schema.js';
-export type * from './errors.js';
-export * from './parse.js';
-export * from './stringify.js';
-export * from './mutate.js';

package/src/mutate.ts

@@ -1,151 +0,0 @@
-import type { InferFilters, Schema } from './types.js';
-
-/**
- * Checks shallow equality between two plain objects (own enumerable string keys only).
- */
-function shallowEqual(a: unknown, b: unknown): boolean {
-  if (a === b) {
-    return true;
-  }
-  if (
-    typeof a !== 'object' ||
-    a === null ||
-    typeof b !== 'object' ||
-    b === null
-  ) {
-    return false;
-  }
-  const aObj = a as Record<string, unknown>;
-  const bObj = b as Record<string, unknown>;
-  const aKeys = Object.keys(aObj);
-  const bKeys = Object.keys(bObj);
-  if (aKeys.length !== bKeys.length) {
-    return false;
-  }
-  for (const k of aKeys) {
-    if (aObj[k] !== bObj[k]) {
-      return false;
-    }
-  }
-  return true;
-}
-
-/**
- * Sets or unsets a specific operator value on a field while preserving reference
- * equality when nothing changes.
- *
- * @param filters - Current filters object that will be treated as immutable input.
- * @param _schema - Schema reference (reserved for future validation hooks).
- * @param field - Field key to update.
- * @param operator - Operator name to set or remove.
- * @param value - New operator value; pass `undefined` to remove it.
- */
-export function setFilter<
-  S extends Schema,
-  F extends keyof S,
-  O extends keyof NonNullable<InferFilters<S>[F]>,
->(
-  filters: Readonly<InferFilters<S>>,
-  _schema: S, // reserved for future validation hooks
-  field: F,
-  operator: O,
-  value: NonNullable<InferFilters<S>[F]>[O] | undefined,
-): InferFilters<S> {
-  const currentField = filters[field];
-  if (value === undefined) {
-    if (currentField === undefined) {
-      return filters as InferFilters<S>;
-    }
-    const { [operator]: _removed, ...rest } = currentField as Record<
-      string,
-      unknown
-    >;
-    if (Object.keys(rest).length === 0) {
-      const { [field]: _f, ...clone } = filters as Record<string, unknown>;
-      return clone as InferFilters<S>;
-    }
-    return { ...filters, [field]: rest } as InferFilters<S>;
-  }
-  const newField = {
-    ...(currentField as Record<string, unknown> | undefined),
-    [operator]: value,
-  };
-  if (currentField !== undefined && shallowEqual(currentField, newField)) {
-    return filters as InferFilters<S>;
-  }
-  return { ...filters, [field]: newField } as InferFilters<S>;
-}
-
-/**
- * Removes either an entire field or a specific operator from the filters object.
- *
- * @param filters - Current filters object (treated immutably).
- * @param field - Field name to alter.
- * @param operator - Optional operator to remove; omit to drop the whole field.
- */
-export function removeFilter<S extends Schema, F extends keyof S>(
-  filters: Readonly<InferFilters<S>>,
-  field: F,
-  operator?: keyof NonNullable<InferFilters<S>[F]>,
-): InferFilters<S> {
-  const currentField = filters[field];
-  if (currentField === undefined) {
-    return filters as InferFilters<S>;
-  }
-  if (operator === undefined) {
-    const { [field]: _removed, ...clone } = filters as Record<string, unknown>;
-    return clone as InferFilters<S>;
-  }
-  const { [operator]: _opRemoved, ...rest } = currentField as Record<
-    string,
-    unknown
-  >;
-  if (Object.keys(rest).length === 0) {
-    const { [field]: _f, ...clone } = filters as Record<string, unknown>;
-    return clone as InferFilters<S>;
-  }
-  return { ...filters, [field]: rest } as InferFilters<S>;
-}
-
-/**
- * Merges a patch of filters into an existing filters object while preserving reference
- * identity for unchanged fields.
- *
- * @param base - Original filters.
- * @param patch - Filters to overlay.
- */
-export function mergeFilters<S extends Schema>(
-  base: Readonly<InferFilters<S>>,
-  patch: Readonly<InferFilters<S>>,
-): InferFilters<S> {
-  let changed = false;
-  const result: Partial<InferFilters<S>> = { ...base };
-  for (const key of Object.keys(patch) as (keyof S)[]) {
-    const existing = base[key];
-    const incoming = patch[key];
-    if (incoming === undefined) {
-      // skip undefined incoming
-    } else if (existing === undefined) {
-      result[key] = incoming as InferFilters<S>[typeof key];
-      changed = true;
-    } else if (!shallowEqual(existing, incoming)) {
-      result[key] = incoming as InferFilters<S>[typeof key];
-      changed = true;
-    }
-  }
-  if (changed) {
-    return result as InferFilters<S>;
-  }
-  return base as InferFilters<S>;
-}
-
-/**
- * Determines if the filters object is empty (no fields present).
- *
- * @param filters - Filters to inspect.
- */
-export function isEmpty<S extends Schema>(
-  filters: Readonly<InferFilters<S>>,
-): boolean {
-  return Object.keys(filters).length === 0;
-}

package/src/parse.ts

@@ -1,244 +0,0 @@
-import type {
-  Schema,
-  Operator,
-  ListOperator,
-  BetweenOperator,
-  InferFilters,
-  FieldDescriptor,
-  ParseResult,
-} from './types.js';
-import type { Diagnostic } from './errors.js';
-
-const BETWEEN: BetweenOperator = 'between';
-const LIST_OPS: readonly ListOperator[] = ['in', 'nin'];
-
-interface InternalAccumulator<S extends Schema> {
-  filters: InferFilters<S>;
-  diagnostics: Diagnostic[];
-}
-
-/** Shallow clone plus ensure field object helper (immutable update). */
-function ensureFieldObject<S extends Schema>(
-  filters: InferFilters<S>,
-  field: string,
-): { container: InferFilters<S>; target: Record<string, unknown> } {
-  const existing = filters[field as keyof S] as
-    | Record<string, unknown>
-    | undefined;
-  if (existing !== undefined) {
-    return { container: filters, target: existing };
-  }
-  const clone: InferFilters<S> = { ...filters };
-  const created: Record<string, unknown> = {};
-  (clone as Record<string, unknown>)[field] = created;
-  return { container: clone, target: created };
-}
-
-/** Decode component, recording a diagnostic on failure. */
-function decodeValue(
-  value: string,
-  field: string,
-  operator: string,
-  diagnostics: Diagnostic[],
-): string | undefined {
-  try {
-    return decodeURIComponent(value);
-  } catch {
-    diagnostics.push({
-      kind: 'DecodeError',
-      field,
-      operator,
-      detail: 'Failed to decode',
-    });
-    return undefined;
-  }
-}
-
-/** Parse a single raw value according to field kind. */
-function parseSingleValue(
-  descriptor: FieldDescriptor,
-  raw: string,
-): string | number | undefined {
-  if (descriptor.kind === 'number') {
-    if (raw === '') {
-      // Treat empty string as invalid for numeric fields (reject instead of coercing to 0)
-      return undefined;
-    }
-    const n = Number(raw);
-    if (!Number.isFinite(n)) {
-      return undefined;
-    }
-    return n;
-  }
-  return raw;
-}
-
-/** Handle a between operator value. */
-function handleBetween<S extends Schema>(
-  descriptor: FieldDescriptor,
-  decoded: string,
-  field: string,
-  operator: string,
-  acc: InternalAccumulator<S>,
-): void {
-  const parts: string[] = decoded.split(',');
-  if (parts.length !== 2) {
-    acc.diagnostics.push({
-      kind: 'InvalidArity',
-      field,
-      operator,
-      detail: 'Expected exactly 2 values',
-    });
-    return;
-  }
-  const [aRaw, bRaw] = parts as [string, string];
-  const a = parseSingleValue(descriptor, aRaw);
-  const b = parseSingleValue(descriptor, bRaw);
-  if (a === undefined || b === undefined) {
-    acc.diagnostics.push({
-      kind: 'InvalidValue',
-      field,
-      operator,
-      detail: 'One of the between values invalid',
-    });
-    return;
-  }
-  const ensured = ensureFieldObject(acc.filters, field);
-  acc.filters = ensured.container;
-  if (Object.prototype.hasOwnProperty.call(ensured.target, 'between')) {
-    acc.diagnostics.push({ kind: 'DuplicateBetween', field });
-    return;
-  }
-  ensured.target.between = [a, b] as unknown;
-}
-
-/** Handle list operators (in, nin). */
-function handleList<S extends Schema>(
-  descriptor: FieldDescriptor,
-  decoded: string,
-  field: string,
-  operator: string,
-  acc: InternalAccumulator<S>,
-): void {
-  const listRaw = decoded.split(',');
-  const parsedList: (string | number)[] = [];
-  for (const item of listRaw) {
-    const parsed = parseSingleValue(descriptor, item);
-    if (parsed === undefined) {
-      acc.diagnostics.push({
-        kind: 'InvalidValue',
-        field,
-        operator,
-        detail: 'List item invalid',
-      });
-    } else {
-      parsedList.push(parsed);
-    }
-  }
-  if (parsedList.length === 0) {
-    return;
-  }
-  const ensured = ensureFieldObject(acc.filters, field);
-  acc.filters = ensured.container;
-  const targetObj: Record<string, unknown> = ensured.target;
-  const existing = targetObj[operator];
-  if (Array.isArray(existing)) {
-    targetObj[operator] = [...existing, ...parsedList];
-  } else {
-    targetObj[operator] = parsedList;
-  }
-}
-
-/** Handle scalar operator values. */
-function handleScalar<S extends Schema>(
-  descriptor: FieldDescriptor,
-  decoded: string,
-  field: string,
-  operator: string,
-  acc: InternalAccumulator<S>,
-): void {
-  const scalar = parseSingleValue(descriptor, decoded);
-  if (scalar === undefined) {
-    acc.diagnostics.push({ kind: 'InvalidValue', field, operator });
-    return;
-  }
-  const ensured = ensureFieldObject(acc.filters, field);
-  acc.filters = ensured.container;
-  const scalarTarget: Record<string, unknown> = ensured.target;
-  scalarTarget[operator] = scalar;
-}
-
-/**
- * Parses a raw search string (leading `?` optional) according to the provided schema
- * and returns the filters plus diagnostics.
- *
- * @param rawSearch - Query string to parse (with or without the leading question mark).
- * @param schema - Schema describing allowed fields and operators.
- * @returns Parsed filters alongside non-blocking diagnostics.
- */
-export function parse<S extends Schema>(
-  rawSearch: string,
-  schema: S,
-): ParseResult<S> {
-  const acc: InternalAccumulator<S> = { filters: {}, diagnostics: [] };
-  let search = rawSearch;
-  if (search.startsWith('?')) {
-    search = search.slice(1);
-  }
-  if (search.trim() === '') {
-    return acc;
-  }
-  const segments = search.split('&');
-  for (const seg of segments) {
-    const eqIdx = seg.indexOf('=');
-    const validBasic = seg !== '' && eqIdx !== -1;
-    if (validBasic) {
-      const rawKey = seg.slice(0, eqIdx);
-      const rawVal = seg.slice(eqIdx + 1);
-      const lastDot = rawKey.lastIndexOf('.');
-      // Case 1: key with explicit operator (field.op)
-      const explicitShape = !(lastDot <= 0 || lastDot === rawKey.length - 1);
-      if (explicitShape) {
-        const field = rawKey.slice(0, lastDot);
-        const operator = rawKey.slice(lastDot + 1) as Operator;
-        const descriptor = schema[field];
-        const descOk = descriptor?.operators.includes(operator) === true;
-        if (!descOk) {
-          if (descriptor == null) {
-            acc.diagnostics.push({ kind: 'UnknownField', field });
-          } else {
-            acc.diagnostics.push({ kind: 'UnknownOperator', field, operator });
-          }
-        } else {
-          const decoded = decodeValue(rawVal, field, operator, acc.diagnostics);
-          if (decoded !== undefined) {
-            const isList = (LIST_OPS as readonly string[]).includes(operator);
-            if (operator === BETWEEN) {
-              handleBetween(descriptor, decoded, field, operator, acc);
-            } else if (isList) {
-              handleList(descriptor, decoded, field, operator, acc);
-            } else {
-              handleScalar(descriptor, decoded, field, operator, acc);
-            }
-          }
-        }
-      } else if (lastDot === -1) {
-        // implicit equality (no dot) => operator 'eq'
-        const field = rawKey;
-        const operator: Operator = 'eq';
-        const descriptor = schema[field];
-        if (descriptor == null) {
-          acc.diagnostics.push({ kind: 'UnknownField', field });
-        } else if (!descriptor.operators.includes(operator)) {
-          acc.diagnostics.push({ kind: 'UnknownOperator', field, operator });
-        } else {
-          const decoded = decodeValue(rawVal, field, operator, acc.diagnostics);
-          if (decoded !== undefined) {
-            handleScalar(descriptor, decoded, field, operator, acc);
-          }
-        }
-      }
-    }
-  }
-  return acc;
-}

package/src/schema.ts

@@ -1,81 +0,0 @@
-import type {
-  FieldDescriptor,
-  NumberFieldDescriptor,
-  Schema,
-  StringFieldDescriptor,
-  Operator,
-} from './types.js';
-
-const DEFAULT_NUMBER_OPERATORS: readonly Operator[] = [
-  'gt',
-  'gte',
-  'lt',
-  'lte',
-  'eq',
-  'neq',
-  'between',
-  'in',
-  'nin',
-];
-const DEFAULT_STRING_OPERATORS: readonly Operator[] = [
-  'contains',
-  'sw',
-  'ew',
-  'eq',
-  'neq',
-  'in',
-  'nin',
-];
-
-/**
- * Create a numeric field descriptor with a given operator whitelist.
- */
-export function numberField(
-  ops: readonly Operator[] = DEFAULT_NUMBER_OPERATORS,
-): NumberFieldDescriptor {
-  return {
-    kind: 'number',
-    operators: ops,
-    parse(raw: string): number | undefined {
-      if (raw === '') {
-        return undefined;
-      }
-      const n = Number(raw);
-      if (Number.isFinite(n)) {
-        return n;
-      }
-      return undefined;
-    },
-    // Accept unknown to satisfy base interface intersection; caller ensures type correctness
-    serialize(value: unknown): string {
-      return String(value as number);
-    },
-  } as NumberFieldDescriptor;
-}
-
-/**
- * Create a string field descriptor with a given operator whitelist.
- */
-export function stringField(
-  ops: readonly Operator[] = DEFAULT_STRING_OPERATORS,
-): StringFieldDescriptor {
-  return {
-    kind: 'string',
-    operators: ops,
-    parse(raw: string): string | undefined {
-      return raw;
-    },
-    serialize(value: unknown): string {
-      return String(value as string);
-    },
-  } as StringFieldDescriptor;
-}
-
-/**
- * Freeze and return the schema (immutability guard for consumers).
- */
-export function defineSchema<S extends Record<string, FieldDescriptor>>(
-  schema: S,
-): Schema & S {
-  return Object.freeze({ ...schema });
-}

package/src/stringify.ts

@@ -1,83 +0,0 @@
-import type { InferFilters, Schema, Operator } from './types.js';
-
-/**
- * Builds the encoded key portion for a field/operator pair (implicit `eq` has no dot suffix).
- */
-function encodeKey(field: string, op: Operator): string {
-  if (op === 'eq') return field; // implicit equality form
-  return `${field}.${op}`;
-}
-
-/**
- * Serializes a filters object into a canonical query string respecting the schema operator ordering.
- *
- * @param filters - Parsed filters to encode.
- * @param schema - Schema used to determine operator ordering and formatting.
- * @returns Query string without leading question mark.
- */
-export function stringify<S extends Schema>(
-  filters: InferFilters<S>,
-  schema: S,
-): string {
-  const parts: string[] = [];
-  for (const field of Object.keys(schema)) {
-    const value = filters[field as keyof S];
-    const descriptor = schema[field];
-    if (value === undefined || descriptor === undefined) {
-      // skip absent
-    } else {
-      for (const op of descriptor.operators) {
-        if (op === 'eq') {
-          const scalar = (value as Record<string, unknown>)[op];
-          if (scalar !== undefined) {
-            let printable: unknown = scalar;
-            if (
-              typeof printable !== 'string' &&
-              typeof printable !== 'number'
-            ) {
-              printable = JSON.stringify(printable);
-            }
-            parts.push(
-              `${encodeKey(field, op)}=${encodeURIComponent(String(printable))}`,
-            );
-          }
-        } else if (op === 'between') {
-          const tuple = (value as Record<string, unknown>).between as
-            | unknown[]
-            | undefined;
-          if (Array.isArray(tuple) && tuple.length === 2) {
-            const first = encodeURIComponent(String(tuple[0]));
-            const second = encodeURIComponent(String(tuple[1]));
-            parts.push(`${encodeKey(field, op)}=${first},${second}`);
-          }
-        } else if (op === 'in' || op === 'nin') {
-          const list = (value as Record<string, unknown>)[op] as
-            | unknown[]
-            | undefined;
-          if (Array.isArray(list) && list.length > 0) {
-            const encodedItems = list
-              .map((v) => {
-                return encodeURIComponent(String(v));
-              })
-              .join(',');
-            parts.push(`${encodeKey(field, op)}=${encodedItems}`);
-          }
-        } else {
-          const scalar = (value as Record<string, unknown>)[op];
-          if (scalar !== undefined) {
-            let printable: unknown;
-            if (typeof scalar === 'string' || typeof scalar === 'number') {
-              printable = scalar;
-            } else {
-              printable = JSON.stringify(scalar);
-            }
-            parts.push(
-              `${encodeKey(field, op)}=${encodeURIComponent(String(printable))}`,
-            );
-          }
-        }
-      }
-    }
-  }
-  return parts.join('&');
-}

package/src/types.ts

@@ -1,104 +0,0 @@
-import type { Diagnostic } from './errors.js';
-
-/**
- * Operators that take a single scalar value (numbers or strings) in the filter schema.
- */
-export type ScalarOperator =
-  | 'gt'
-  | 'gte'
-  | 'lt'
-  | 'lte'
-  | 'eq'
-  | 'neq'
-  | 'contains'
-  | 'sw'
-  | 'ew';
-/** Operator representing a range of two values. */
-export type BetweenOperator = 'between';
-/** Operators whose values are lists. */
-export type ListOperator = 'in' | 'nin';
-/** All supported operator kinds. */
-export type Operator = ScalarOperator | BetweenOperator | ListOperator;
-
-/** Primitive field kinds supported by the schema. */
-export type PrimitiveKind = 'number' | 'string';
-
-/**
- * Base descriptor shared by number and string fields.
- */
-export interface FieldDescriptorBase<TKind extends PrimitiveKind> {
-  readonly kind: TKind;
-  readonly operators: readonly Operator[];
-  readonly parse?: (raw: string) => unknown;
-  readonly serialize?: (value: unknown) => string;
-}
-
-/** Descriptor for numeric fields. Provides numeric parsing/serialisation hooks. */
-export type NumberFieldDescriptor = FieldDescriptorBase<'number'> & {
-  readonly parse?: (raw: string) => number | undefined;
-  readonly serialize?: (value: number) => string;
-};
-/** Descriptor for string fields. Provides string parsing/serialisation hooks. */
-export type StringFieldDescriptor = FieldDescriptorBase<'string'> & {
-  readonly parse?: (raw: string) => string | undefined;
-  readonly serialize?: (value: string) => string;
-};
-
-/** Descriptor accepted by the schema (number or string). */
-export type FieldDescriptor = NumberFieldDescriptor | StringFieldDescriptor;
-
-/** Immutable mapping between field keys and their descriptors. */
-export type Schema = Readonly<Record<string, FieldDescriptor>>;
-
-// Infer operator mapping for a single field descriptor
-type OperatorKeys<D extends FieldDescriptor> = Extract<
-  D['operators'][number],
-  ScalarOperator
->;
-type ScalarMap<D extends FieldDescriptor> =
-  D extends FieldDescriptorBase<'number'>
-    ? Record<OperatorKeys<D>, number | undefined>
-    : Record<OperatorKeys<D>, string | undefined>;
-
-type BetweenMap<D extends FieldDescriptor> =
-  'between' extends D['operators'][number]
-    ? {
-        between?: D extends FieldDescriptorBase<'number'>
-          ? readonly [number, number]
-          : readonly [string, string];
-      }
-    : Record<never, never>;
-
-type ListOps<D extends FieldDescriptor> = Extract<
-  D['operators'][number],
-  ListOperator
->;
-type ListMap<D extends FieldDescriptor> = ('in' extends ListOps<D>
-  ? {
-      in?: D extends FieldDescriptorBase<'number'>
-        ? readonly number[]
-        : readonly string[];
-    }
-  : Record<never, never>) &
-  ('nin' extends ListOps<D>
-    ? {
-        nin?: D extends FieldDescriptorBase<'number'>
-          ? readonly number[]
-          : readonly string[];
-      }
-    : Record<never, never>);
-
-export type InferField<D extends FieldDescriptor> = Partial<
-  ScalarMap<D> & BetweenMap<D> & ListMap<D>
->;
-
-/** Filters map inferred from a schema definition. */
-export type InferFilters<S extends Schema> = {
-  [K in keyof S]?: InferField<S[K]>;
-};
-
-/** Result returned by the `parse` function: parsed filters plus diagnostics. */
-export interface ParseResult<S extends Schema> {
-  readonly filters: InferFilters<S>;
-  readonly diagnostics: Diagnostic[];
-}

package/tools/build-package.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-npm run build:package:esm
-npm run build:package:types

package/tools/test-build-package.sh

@@ -1,4 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-npm run build:package:types

package/tsconfig.build.json

@@ -1,8 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "./src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "lib", "**/__tests__/**"]
-}

package/tsconfig.esm.json

@@ -1,7 +0,0 @@
-{
-  "extends": "./tsconfig.build.json",
-  "compilerOptions": {
-    "module": "ES2020",
-    "outDir": "./lib/esm"
-  }
-}