docs: give sub-package READMEs a consistent, richer layout - #836
Conversation
|
Warning Review limit reached
Next review available in: 5 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (18)
📝 WalkthroughWalkthroughREADME files and package metadata were refreshed across core, parsers, URL codec, memory, SQL, TypeORM, and documentation packages. Updates add branded headers, feature summaries, package-family tables, usage details, and more specific package descriptions. ChangesCore and documentation package presentation
Parser and URL dialect documentation
Query adapter documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/sql/README.md`:
- Line 34: Update the README’s “Parameterized always” statement to guarantee
protection only for bound filter values, and explicitly state that
caller-composed SELECT/FROM/JOIN identifiers or SQL fragments still require
validation. Remove the broad “No SQL injection surface” claim while preserving
the existing parameterization description.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 301d82fa-1fc1-4cd1-bdad-273052ef6127
📒 Files selected for processing (16)
packages/codec-url/README.mdpackages/core/README.mdpackages/core/package.jsonpackages/docs/README.mdpackages/memory/README.mdpackages/memory/package.jsonpackages/parser-expression/README.mdpackages/parser-expression/package.jsonpackages/parser-mongo/README.mdpackages/parser-mongo/package.jsonpackages/parser-simple/README.mdpackages/parser-simple/package.jsonpackages/sql/README.mdpackages/sql/package.jsonpackages/typeorm/README.mdpackages/typeorm/package.json
| Part of [**rapiq**](https://github.com/tada5hi/rapiq) — typed REST queries: *build, transport, validate, execute.* | ||
| This is the dialect-agnostic **execute** layer: it renders a validated `Query` into clause fragments you compose into a `SELECT`. It is also the foundation the [TypeORM adapter](https://www.npmjs.com/package/@rapiq/typeorm) builds on. | ||
|
|
||
| - 🔒 **Parameterized always** — filter values are bound, never string-interpolated. No SQL injection surface. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Narrow the injection guarantee to filter values.
@rapiq/sql binds filter values, but it returns fragments and leaves final SELECT/FROM/JOIN composition to the caller (Line [81]). “No SQL injection surface” may cause consumers to trust unvalidated identifiers or caller-supplied fragments. Limit the claim to filter-value injection and state that caller-composed SQL still requires validation.
Suggested wording
- - 🔒 **Parameterized always** — filter values are bound, never string-interpolated. No SQL injection surface.
+ - 🔒 **Parameterized always** — filter values are bound, never string-interpolated. Caller-composed identifiers and SQL fragments still require validation.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - 🔒 **Parameterized always** — filter values are bound, never string-interpolated. No SQL injection surface. | |
| - 🔒 **Parameterized always** — filter values are bound, never string-interpolated. Caller-composed identifiers and SQL fragments still require validation. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/sql/README.md` at line 34, Update the README’s “Parameterized
always” statement to guarantee protection only for bound filter values, and
explicitly state that caller-composed SELECT/FROM/JOIN identifiers or SQL
fragments still require validation. Remove the broad “No SQL injection surface”
claim while preserving the existing parameterization description.
4c12cef to
1d81cc1
Compare
Bring every packages/*/README.md up to the standard set by the root README: a centered logo + tagline header, npm/types/license badges, nav links, feature highlights, and a shared "rapiq family" table for cross-package discovery. Expand the @rapiq/typeorm usage substantially (request-handler example, relation join strategies, partial application, options table) and add a "what a query becomes" mapping table, plus fragment-output examples for @rapiq/sql. Refresh the stale npm `description` fields (e.g. @rapiq/core no longer reads "A tiny library which provides utility types/functions"). Record a prose style convention in .agents/conventions.md (no em or en dashes in written text) and apply it across all READMEs, including the root README.md.
1d81cc1 to
3913e78
Compare
Adds the package page (parameter mapping, metadata contract, negation, per-connector case semantics) and the package README in the layout established by #836, lists the adapter in the shared "rapiq family" table of every sibling README, and references it from the overview, installation and executing-queries pages.
Adds the package page (parameter mapping, metadata contract, negation and same-element semantics, per-connector case behaviour) and the package README in the layout established by #836, lists the adapter in the shared "rapiq family" table of every sibling README, and references it from the overview, installation and executing-queries pages.
* feat(core): add distributeNegation plan transform
Eliminates group negation from a condition plan by pushing it down to
the leaves: De Morgan over compounds, leaf twins toggled, not(ordering)
rewritten as the dual operator OR a null check (the complement derived
from the semantics table's compare ranges, keeping the table the single
authority), and residual wrappers kept only around mod/size, which have
no complement form.
planCondition retains group negation because sql and memory render it
two-valued cheaply (a CASE wrapper, a `!`). Backends without a
two-valued NOT of their own, prisma first and the other structured-args
ORMs of plan 023 next, consume this transform instead of re-deriving
operator semantics locally.
The transform encodes the settled negation contract: group negation is
the two-valued complement per binding with the quantifier outermost, so
it commutes through elemMatch (not(elemMatch(c)) selects records with
an element failing c, not records without a matching element).
* feat(prisma): add prisma adapter
Serializes a parsed Query into a Prisma findMany argument object:
filters to `where`, fields to `select`, relations to `include`, sort to
`orderBy`, pagination to `take`/`skip`. The adapter is stateless and
pure: `execute` maps a value to a value, composition happens before
serialization (mergeQueries, filters.and()), and @prisma/client is
neither a runtime nor a peer dependency.
The `where` is produced by a pipeline of pure passes: planCondition,
core's distributeNegation, quantifier factoring, then a leaf-literal
table. Prisma's three-valued `not`/`NOT` is never relied upon.
Cross-backend semantics hold exactly: relation traversal quantifies
existentially with the quantifier outermost (a left join evaluated per
row), conditions sharing a to-many path within a conjunction are
factored into ONE `some` scope so they bind to the same element as in
sql/typeorm/memory (mixed trees are expanded distributively first,
capped with a typed error), and every quantifier gains its `none: {}`
or absence arm exactly when the interior holds at the all-null binding
an empty collection contributes.
`provider` and `metadata` are required: each metadata fact (relation,
cardinality, nullability, string-typedness) changes what a valid prisma
filter looks like, so a wrong guess is a validation error rather than
degradation.
Parity is measured rather than modelled: the engine suite runs the
matrix through a real prisma client (sqlite by default, postgres under
DB_TYPE=postgres) and cross-checks every condition against
@rapiq/memory and an in-test evaluator, including a mixed-element
record that pins same-element binding and the per-binding complement
of elemMatch.
* ci: run the @rapiq/prisma engine specs in the database job
All of the package's engine-backed specs need a generated prisma client,
so they live behind `test:db` and the default `tests` job stays
codegen-free. The postgres matrix entry is the only place where
`mode: 'insensitive'` exists at all, so the case contract and the
ILIKE-wildcard veto can only be measured there.
* docs: document @rapiq/prisma
Adds the package page (parameter mapping, metadata contract, negation
and same-element semantics, per-connector case behaviour) and the
package README in the layout established by #836, lists the adapter in
the shared "rapiq family" table of every sibling README, and references
it from the overview, installation and executing-queries pages.
Summary
Brings every
packages/*/README.mdup to the standard already set by the rootREADME.md. The sub-package READMEs were previously plain (# @rapiq/x, one-liner, install, usage), which undersold what each package does; the@rapiq/typeormone in particular read as a bare stub.Each README now has a consistent, richer layout:
/betadist-tag, since these publish underbeta, notlatest), a TypeScript "types" badge, and MIT license; colors match the logo gradient@rapiq/typeorm (expanded)
The flagship package now has a substantial Usage section: a Quick start, a realistic request-handler example (showing that application-owned
WHEREscoping survives because filters useandWhere), relation join strategies (joinAndSelect/joinType/hydrationMode/onJoin, verified againstpackages/typeorm/src), and applying part of a query via the public sub-adapters. It also keeps the "what a query becomes" mapping table (filters -> andWhere,relations -> leftJoinAndSelect,fields -> select,sort -> orderBy,pagination -> take/skip).@rapiq/sqlshows the fragment-output shape.npm descriptions
Refreshed the stale
descriptionfields (e.g.@rapiq/coreno longer reads "A tiny library which provides utility types/functions…"). Package versions are untouched (eachpackage.jsonchange is the description line only).Prose convention
Recorded a style rule in
.agents/conventions.md: no em or en dashes in written text (READMEs, docs, comments, commit/PR bodies), with the preferred substitutes. The READMEs follow it.Notes
packages/*, guide pages, typeorm recipe/migration) were verified to exist, and everypackage.jsonstill parses.<img>-SVG support has historically been spotty. Guaranteed on GitHub; if the logo does not show on npm package pages, converting it to a PNG is the fallback.