REST API'da filtrlash, saralash va maydon tanlash: query parametrlar

$ curl $A/vazifalar?teg=uy&fields=matn,teglar
{"vazifalar":[{"id":1,"matn":"Non olish #uy","teglar":["uy"]},
  {"id":3,"matn":"Sut #uy #bozor","teglar":["uy","bozor"]}],
  "sahifa":{"limit":20,"keyingi":null}}
$ curl $A/vazifalar?bajarildi=true&sort=-yangilandi&fields=matn,yangilandi
{"vazifalar":[{"id":4,"matn":"Kitob o'qish #o'quv","yangilandi":"…32.899Z"},
  {"id":2,"matn":"Hisobot yozish #ish","yangilandi":"…32.635Z"}], …}
$ curl $A/vazifalar?q=OLISH
{"vazifalar":[{"id":1,"matn":"Non olish #uy",…}], …}

const SARALASH = ["id", "matn", "bajarildi", "yaratildi"];

function saralashniOqi(x) {
  if (x === undefined) return [];
  return x.split(",").map((qism) => {
    const kamayish = qism.startsWith("-");
    const maydon = kamayish ? qism.slice(1) : qism;
    if (!SARALASH.includes(maydon)) {
      throw new Error(`sort: noma'lum maydon "${maydon}"`);
    }
    return { maydon, kamayish };
  });
}

function sarala(royxat, kalitlar) {
  // oxiriga doim id — teng qiymatlarda ham tartib barqaror
  const k = [...kalitlar.filter((s) => s.maydon !== "id"),
    kalitlar.find((s) => s.maydon === "id") ?? { maydon: "id" }];
  return [...royxat].sort((a, b) => {
    for (const { maydon, kamayish } of k) {
      if (a[maydon] === b[maydon]) continue;
      const n = a[maydon] < b[maydon] ? -1 : 1;
      return kamayish ? -n : n;
    }
    return 0;
  });
}

const vazifalar = [
  { id: 1, matn: "Non olish", bajarildi: false },
  { id: 2, matn: "Hisobot", bajarildi: true },
  { id: 3, matn: "Sut", bajarildi: false },
  { id: 4, matn: "Kitob o'qish", bajarildi: true },
];
const tartib = sarala(vazifalar, saralashniOqi("-bajarildi,matn"));
console.log(tartib.map((v) => v.id).join(", "));
try {
  saralashniOqi("-parol");
} catch (xato) {
  console.log(xato.message);
}

2, 4, 1, 3
sort: noma'lum maydon "parol"

$ curl $A/vazifalar?sort=parol
{"xato":"sort: noma'lum maydon \"parol\" (mumkin: id, matn, bajarildi, yaratildi, yangilandi)"}

const MAYDONLAR = ["id", "matn", "bajarildi", "teglar", "yaratildi"];

function maydonlarniOqi(x) {
  if (x === undefined) return undefined;
  const m = x.split(",");
  for (const nom of m) {
    if (!MAYDONLAR.includes(nom)) throw new Error(`fields: "${nom}"`);
  }
  return [...new Set(["id", ...m])]; // id doim, takrorsiz
}

const proyeksiya = (v, maydonlar) => maydonlar === undefined
  ? v : Object.fromEntries(maydonlar.map((m) => [m, v[m]]));

const v = { id: 7, matn: "Non olish #uy", bajarildi: false,
  teglar: ["uy"], yaratildi: "2026-10-24T05:04:51.972Z" };
for (const fields of ["matn,teglar", "matn,id,matn"]) {
  const natija = proyeksiya(v, maydonlarniOqi(fields));
  console.log(JSON.stringify(natija));
}

{"id":7,"matn":"Non olish #uy","teglar":["uy"]}
{"id":7,"matn":"Non olish #uy"}

?teg=uy&teg=bozor     takrorlangan kalit (vazifalar-api)
?teg=uy,bozor         vergul bilan
?teg[]=uy&teg[]=bozor qavs bilan (PHP, qs)

GET /q?teg=uy&teg=ish&sahifa=2 → {"teg":["uy","ish"],"sahifa":"2"}
GET /q?filtr[bajarildi]=true → {"filtr[bajarildi]":"true"}
GET /q?a=1&a=2&a=3 → {"a":["1","2","3"]}

const teglar = (Array.isArray(teg) ? teg : [teg])
  .map((t) => (typeof t === "string"
    ? t.replace(/^#/, "").toLowerCase() : ""));

extended ?parol[$ne]=x → {"parol":{"$ne":"x"}}
extended ?teg[]=uy&teg[]=ish → {"teg":["uy","ish"]}
extended ?teg[0]=uy&teg[25]=ish → {"teg":{"0":"uy","25":"ish"}}
extended ?a[b][c][d][e][f][g]=1 → {"a":{"b":{"c":{"d":{"e":{"f":{"[g]":"1"}}}}}}}

$ curl $A/vazifalar?sahifa=2
{"xato":"noma'lum parametr: sahifa"}

// ombor.ts — repository interfeysi: xizmat saqlash qanday
// ishlashini bilmaydi. Hamma metod async — 26-qismda Postgres (pg) bilan
// almashganda chaqiruvchi kod o'zgarmaydi
import type { Vazifa, VazifaOzgarishi, YangiVazifa }
  from "./vazifa.ts";

/** Saralash mumkin bo'lgan maydonlar (oq ro'yxat — SQL'da ustun
 *  nomi bo'ladi, foydalanuvchi matni emas) */
export const SARALASH_MAYDONLARI =
  ["id", "matn", "bajarildi", "yaratildi", "yangilandi"] as const;
export type SaralashMaydoni = (typeof SARALASH_MAYDONLARI)[number];
export type Saralash = { maydon: SaralashMaydoni; kamayish: boolean };

export type Filtr = {
  bajarildi?: boolean;
  /** hammasi bo'lishi kerak (AND), kichik harfda */
  teglar?: string[];
  /** matn ichida, katta-kichik harfsiz */
  qidiruv?: string;
};

/** Keyset kursori: oxirgi qatorning saralash kalitlari qiymatlari
 *  (saralash tartibida) + id */
export type KursorQiymati = (string | number | boolean)[];

export type Sahifalash =
  | { tur: "offset"; offset: number }
  | { tur: "kursor"; keyin?: KursorQiymati };

export type RoyxatSorovi = {
  filtr: Filtr;
  /** bo'sh bo'lsa — id bo'yicha o'sish; ombor oxiriga doim id
   *  qo'shadi (barqaror tartib) */
  saralash: Saralash[];
  limit: number;
  sahifa: Sahifalash;
  /** jami sonini ham hisoblash (Postgres'da alohida COUNT —
   *  qimmat) */
  jami?: boolean;
};

export type RoyxatNatija = {
  vazifalar: Vazifa[];
  /** keyingi sahifa bormi — kursor rejimida keyingi kursor
   *  qiymatlari */
  keyingi?: KursorQiymati;
  borKeyingi: boolean;
  jami?: number;
};

export type TegSoni = { teg: string; soni: number };

export interface VazifaOmbori {
  royxat(sorov: RoyxatSorovi): Promise<RoyxatNatija>;
  /** filtrga mos vazifalar soni (limit va sahifasiz) */
  soni(filtr: Filtr): Promise<number>;
  ol(id: number): Promise<Vazifa | undefined>;
  yarat(yangi: YangiVazifa): Promise<Vazifa>;
  /** @returns undefined — bunday id yo'q */
  yangila(id: number, ozgarish: VazifaOzgarishi):
    Promise<Vazifa | undefined>;
  /** @returns false — bunday id yo'q */
  ochir(id: number): Promise<boolean>;
  /** teglar va nechta vazifada — ko'pidan kamiga */
  teglar(): Promise<TegSoni[]>;
}

// sorov.ts — GET /vazifalar query parametrlarini tekshirib
// RoyxatSorovi ga aylantirish (qo'lda; #30 da Zod). Konvensiya:
// ?bajarildi=true&teg=uy&teg=ish&q=non&sort=-yaratildi,matn
//   &fields=id,matn&limit=20&offset=40 | &cursor=...&jami=true
import { HttpXato } from "../umumiy/http-xato.ts";
import { kursorOqi } from "../umumiy/kursor.ts";
import { SARALASH_MAYDONLARI } from "./ombor.ts";
import type { Filtr, RoyxatSorovi, Saralash, SaralashMaydoni }
  from "./ombor.ts";
import type { Vazifa } from "./vazifa.ts";

export const SUKUT_LIMIT = 20;
export const MAKS_LIMIT = 100;
export const MAKS_OFFSET = 10_000;
const MAYDONLAR = ["id", "matn", "bajarildi", "teglar", "yaratildi",
  "yangilandi"] as const;
export type Maydon = (typeof MAYDONLAR)[number];
const RUXSAT = new Set(["bajarildi", "teg", "q", "sort", "fields",
  "limit", "offset", "cursor", "jami"]);
const TEG = /^[\p{L}\p{N}_'‘’]{1,50}$/u;

export type TekshirilganSorov =
  { sorov: RoyxatSorovi; maydonlar?: Maydon[]; imzo: string };

type Query = Record<string, unknown>;

function bitta(q: Query, nom: string): string | undefined {
  const x = q[nom];
  if (x === undefined) return undefined;
  if (typeof x !== "string") {
    throw new HttpXato(400, `${nom} bir marta berilishi kerak`);
  }
  return x;
}

function mantiqiy(q: Query, nom: string): boolean | undefined {
  const x = bitta(q, nom);
  if (x === undefined) return undefined;
  if (x !== "true" && x !== "false") {
    throw new HttpXato(400, `${nom} — true yoki false`);
  }
  return x === "true";
}

function butun(q: Query, nom: string, min: number,
  max: number): number | undefined {
  const x = bitta(q, nom);
  if (x === undefined) return undefined;
  if (!/^\d{1,6}$/.test(x) || Number(x) < min || Number(x) > max) {
    throw new HttpXato(400,
      `${nom} — ${String(min)}..${String(max)} ` +
      "oralig'idagi butun son");
  }
  return Number(x);
}

function saralashniOqi(x: string | undefined): Saralash[] {
  if (x === undefined) return [];
  const natija: Saralash[] = [];
  for (const qism of x.split(",")) {
    const kamayish = qism.startsWith("-");
    const maydon = kamayish ? qism.slice(1) : qism;
    if (!(SARALASH_MAYDONLARI as readonly string[])
      .includes(maydon)) {
      throw new HttpXato(400, `sort: noma'lum maydon "${maydon}" ` +
        `(mumkin: ${SARALASH_MAYDONLARI.join(", ")})`);
    }
    if (natija.some((s) => s.maydon === maydon)) {
      throw new HttpXato(400, `sort: "${maydon}" takrorlangan`);
    }
    natija.push({ maydon: maydon as SaralashMaydoni, kamayish });
  }
  return natija;
}

function maydonlarniOqi(x: string | undefined): Maydon[] | undefined {
  if (x === undefined) return undefined;
  const m = x.split(",");
  for (const nom of m) {
    if (!(MAYDONLAR as readonly string[]).includes(nom)) {
      throw new HttpXato(400, `fields: noma'lum maydon "${nom}"`);
    }
  }
  // id doim — mijoz keyin shu vazifaga murojaat qila olsin
  return [...new Set(["id", ...m])] as Maydon[];
}

export function royxatSorovi(q: Query): TekshirilganSorov {
  for (const k of Object.keys(q)) {
    if (!RUXSAT.has(k)) {
      throw new HttpXato(400, `noma'lum parametr: ${k}`);
    }
  }
  const filtr: Filtr = {};
  const bajarildi = mantiqiy(q, "bajarildi");
  if (bajarildi !== undefined) filtr.bajarildi = bajarildi;
  const teg = q.teg;
  if (teg !== undefined) {
    const teglar = (Array.isArray(teg) ? teg : [teg]).map((t) =>
      (typeof t === "string"
        ? t.replace(/^#/, "").toLowerCase() : ""));
    if (!teglar.every((t) => TEG.test(t))) {
      throw new HttpXato(400,
        "teg — harf, raqam, _ (50 belgigacha)");
    }
    filtr.teglar = [...new Set(teglar)];
  }
  const qidiruv = bitta(q, "q");
  if (qidiruv !== undefined) {
    if (qidiruv.trim() === "" || qidiruv.length > 100) {
      throw new HttpXato(400, "q — 1..100 belgi");
    }
    filtr.qidiruv = qidiruv.trim();
  }
  const saralash = saralashniOqi(bitta(q, "sort"));
  const limit = butun(q, "limit", 1, MAKS_LIMIT) ?? SUKUT_LIMIT;
  const offset = butun(q, "offset", 0, MAKS_OFFSET);
  const kursor = bitta(q, "cursor");
  // Imzo — kursor boshqa filtr/saralash bilan qayta ishlatilmasin
  const imzo = JSON.stringify([saralash, filtr]);
  let sahifa: RoyxatSorovi["sahifa"] =
    { tur: "offset", offset: offset ?? 0 };
  if (kursor !== undefined) {
    if (offset !== undefined) {
      throw new HttpXato(400, "offset va cursor birga berilmaydi");
    }
    const keyin = kursorOqi(kursor, imzo);
    if (keyin === undefined) {
      throw new HttpXato(400,
        "cursor yaroqsiz yoki boshqa saralash/filtr uchun");
    }
    sahifa = { tur: "kursor", keyin };
  } else if (offset === undefined) {
    // Parametrsiz — kursor rejimi (birinchi sahifa);
    // offset faqat aniq so'ralganda
    sahifa = { tur: "kursor" };
  }
  const sorov: RoyxatSorovi = { filtr, saralash, limit, sahifa };
  const jami = mantiqiy(q, "jami");
  if (jami !== undefined) sorov.jami = jami;
  const maydonlar = maydonlarniOqi(bitta(q, "fields"));
  return maydonlar === undefined
    ? { sorov, imzo } : { sorov, maydonlar, imzo };
}

/** Sparse fieldsets: faqat so'ralgan maydonlar */
export function proyeksiya(v: Vazifa,
  maydonlar: readonly Maydon[] | undefined): Partial<Vazifa> {
  if (maydonlar === undefined) return v;
  return Object.fromEntries(maydonlar.map((m) => [m, v[m]]));
}

// royxat-mantiq.ts — xotiradagi (va fayldagi) omborlar uchun filtr,
// saralash, offset va keyset sahifalash. Toza funksiyalar: massiv
// kiradi — natija chiqadi. Postgres ombori (26-qism) buni SQL'da
// qiladi (WHERE, ORDER BY, LIMIT)
import type { Filtr, KursorQiymati, RoyxatNatija, RoyxatSorovi,
  Saralash } from "./ombor.ts";
import type { Vazifa } from "./vazifa.ts";

export function filtrla(vazifalar: readonly Vazifa[],
  filtr: Filtr): Vazifa[] {
  const qidiruv = filtr.qidiruv?.toLowerCase();
  return vazifalar.filter(
    (v) =>
      (filtr.bajarildi === undefined ||
        v.bajarildi === filtr.bajarildi) &&
      (filtr.teglar === undefined ||
        filtr.teglar.every((t) => v.teglar.includes(t))) &&
      (qidiruv === undefined ||
        v.matn.toLowerCase().includes(qidiruv)),
  );
}

/** Saralash kalitlari + id (oxirgi kalit — tenglikda ham tartib
 *  barqaror bo'lsin) */
export function kalitlar(saralash: readonly Saralash[]): Saralash[] {
  const k = saralash.filter((s) => s.maydon !== "id");
  const id = saralash.find((s) => s.maydon === "id");
  return [...k, id ?? { maydon: "id", kamayish: false }];
}