trilean-sql 0.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,34 @@
1
+ //#region src/options.d.ts
2
+ /** The declared SQL value kind of a mapped column. `"timestamp"` names trilean's `instant` kind, whose values are ISO-8601 strings. */
3
+ type SqlParamType = "text" | "number" | "boolean" | "timestamp";
4
+ /** What a `reference` node's key maps onto in the target schema. */
5
+ interface SqlColumnBinding {
6
+ /** The column, optionally qualified with a table or schema by dots (`"orders.total"`). Each dot-separated segment is emitted as its own double-quoted identifier, so a segment may contain any character except a dot itself. */
7
+ column: string;
8
+ /**
9
+ * The column's value kind, if the caller knows it. Optional, and worth supplying: it is the only thing that lets the compiler check a comparison against the column for the kind mismatches trilean itself treats as `wrong-type` -- comparing a text column with `compare` rather than `textCompare`, ordering a boolean, comparing a number against an instant. Left undeclared, those comparisons compile, and PostgreSQL may coerce its way to a definite answer where trilean would have returned indeterminate.
10
+ *
11
+ * It does not affect the emitted SQL, only whether the comparison is emitted at all. Every literal placeholder is already cast to the type its own trilean kind implies, and a comparison that survives the check is one whose operand kinds agree, so there is nothing left for the column's declared kind to change.
12
+ */
13
+ paramType?: SqlParamType;
14
+ }
15
+ interface SqlCompileOptions {
16
+ /** PostgreSQL is the only dialect implemented. It is a required field rather than a default so that adding a second dialect later is a new value here, not a change of behaviour for callers who never said which one they meant. */
17
+ dialect: "postgres";
18
+ /**
19
+ * Maps a `reference` node's key onto a column. Called once per reference occurrence.
20
+ *
21
+ * Only string reference keys reach it: trilean allows any JSON value as a key, and a non-string one is refused as unpushable before this is called. Throwing from here is how a caller rejects a key it has no column for -- the exception propagates out of `compilePredicateNode` unchanged, rather than being wrapped or swallowed.
22
+ */
23
+ columnFor: (referenceKey: string) => SqlColumnBinding;
24
+ }
25
+ interface CompiledSql {
26
+ /** A self-contained boolean expression, always parenthesised, suitable for dropping straight into a `WHERE` clause (or a `CHECK`, a `HAVING`, or a filtered index predicate). It carries no `WHERE` keyword of its own. */
27
+ sql: string;
28
+ /** Positional parameters, in `$1`-first order, to pass alongside `sql`. Every caller-supplied literal in the tree is here; none is ever written into `sql`. */
29
+ params: unknown[];
30
+ }
31
+ /** The PostgreSQL type each declared value kind is cast to. `timestamptz` rather than `timestamp`: trilean's `instant` is an ISO-8601 string that may carry an offset, and parsing one as a naive `timestamp` would silently discard it. */
32
+ declare const POSTGRES_TYPE_NAME: Readonly<Record<SqlParamType, string>>;
33
+ //#endregion
34
+ export { CompiledSql, POSTGRES_TYPE_NAME, SqlColumnBinding, SqlCompileOptions, SqlParamType };
@@ -0,0 +1,10 @@
1
+ //#region src/options.ts
2
+ /** The PostgreSQL type each declared value kind is cast to. `timestamptz` rather than `timestamp`: trilean's `instant` is an ISO-8601 string that may carry an offset, and parsing one as a naive `timestamp` would silently discard it. */
3
+ const POSTGRES_TYPE_NAME = {
4
+ text: "text",
5
+ number: "double precision",
6
+ boolean: "boolean",
7
+ timestamp: "timestamptz"
8
+ };
9
+ //#endregion
10
+ export { POSTGRES_TYPE_NAME };
package/package.json CHANGED
@@ -1,5 +1,101 @@
1
1
  {
2
2
  "name": "trilean-sql",
3
- "version": "0.0.0",
4
- "private": false
3
+ "version": "1.0.1",
4
+ "description": "Compiles a trilean predicate tree into a parameterised SQL WHERE fragment, pushing three-valued logic down onto the database's own NULL propagation instead of evaluating it in process.",
5
+ "type": "module",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/ExaDev/trilean.git",
9
+ "directory": "packages/trilean-sql"
10
+ },
11
+ "homepage": "https://github.com/ExaDev/trilean/tree/main/packages/trilean-sql",
12
+ "bugs": {
13
+ "url": "https://github.com/ExaDev/trilean/issues"
14
+ },
15
+ "exports": {
16
+ ".": {
17
+ "types": {
18
+ "import": "./dist/index.d.ts",
19
+ "require": "./dist/index.d.cts"
20
+ },
21
+ "import": "./dist/index.js",
22
+ "require": "./dist/index.cjs"
23
+ },
24
+ "./*": {
25
+ "types": {
26
+ "import": "./dist/*.d.ts",
27
+ "require": "./dist/*.d.cts"
28
+ },
29
+ "import": "./dist/*.js",
30
+ "require": "./dist/*.cjs"
31
+ }
32
+ },
33
+ "main": "./dist/index.cjs",
34
+ "module": "./dist/index.js",
35
+ "types": "./dist/index.d.ts",
36
+ "files": [
37
+ "dist"
38
+ ],
39
+ "publishConfig": {
40
+ "access": "public",
41
+ "provenance": true,
42
+ "registry": "https://registry.npmjs.org/"
43
+ },
44
+ "sideEffects": false,
45
+ "engines": {
46
+ "node": ">=20"
47
+ },
48
+ "license": "MIT",
49
+ "dependencies": {
50
+ "trilean": "workspace:^"
51
+ },
52
+ "scripts": {
53
+ "build": "turbo run _build",
54
+ "_build": "tsdown",
55
+ "lint": "turbo run _lint",
56
+ "_lint": "eslint . --fix --cache --max-warnings 0",
57
+ "typecheck": "turbo run _typecheck _typecheck:attw",
58
+ "_typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.node.json",
59
+ "_typecheck:attw": "attw --pack",
60
+ "test": "turbo run _test",
61
+ "_test": "vitest run --project unit",
62
+ "test:coverage": "turbo run _test:coverage",
63
+ "_test:coverage": "vitest run --project unit --coverage",
64
+ "test:integration": "turbo run _test:integration",
65
+ "_test:integration": "vitest run --project integration",
66
+ "prepush": "turbo run _prepush",
67
+ "_prepush": "true",
68
+ "prepublishOnly": "pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run test:integration && pnpm run build && publint && attw --pack"
69
+ },
70
+ "keywords": [
71
+ "sql",
72
+ "postgres",
73
+ "predicate",
74
+ "three-valued-logic",
75
+ "query-builder",
76
+ "predicate-pushdown",
77
+ "trilean",
78
+ "rules-engine"
79
+ ],
80
+ "devDependencies": {
81
+ "@arethetypeswrong/cli": "^0.18.5",
82
+ "@electric-sql/pglite": "^0.5.8",
83
+ "@exadev/eslint-config": "^2.10.2",
84
+ "@testcontainers/postgresql": "^12.1.0",
85
+ "@types/node": "^26.4.0",
86
+ "@types/pg": "^8.15.6",
87
+ "@vitest/coverage-v8": "^4.1.11",
88
+ "eslint": "^10.9.1",
89
+ "eslint-config-prettier": "^10.1.8",
90
+ "eslint-plugin-prettier": "^5.5.6",
91
+ "globals": "^17.11.0",
92
+ "pg": "^8.16.3",
93
+ "prettier": "^3.9.6",
94
+ "publint": "^0.3.24",
95
+ "tsdown": "^0.22.14",
96
+ "turbo": "^2.10.12",
97
+ "typescript": "^6.0.3",
98
+ "typescript-eslint": "^8.68.0",
99
+ "vitest": "^4.1.11"
100
+ }
5
101
  }