@loaders.gl/sql 5.0.0-alpha.1 → 5.0.0-alpha.2

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.
Files changed (41) hide show
  1. package/LICENSE +14 -3
  2. package/README.md +49 -0
  3. package/dist/duckdb-sql-source.js +1 -1
  4. package/dist/index.cjs +1699 -19
  5. package/dist/index.cjs.map +3 -4
  6. package/dist/index.d.ts +3 -0
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +2 -0
  9. package/dist/index.js.map +1 -1
  10. package/dist/parse-sql-predicate.d.ts +10 -0
  11. package/dist/parse-sql-predicate.d.ts.map +1 -0
  12. package/dist/parse-sql-predicate.js +316 -0
  13. package/dist/parse-sql-predicate.js.map +1 -0
  14. package/dist/snowflake-sql-source.js +1 -1
  15. package/dist/sql-predicate-schema.d.ts +141 -0
  16. package/dist/sql-predicate-schema.d.ts.map +1 -0
  17. package/dist/sql-predicate-schema.js +205 -0
  18. package/dist/sql-predicate-schema.js.map +1 -0
  19. package/dist/sql-predicate-types.d.ts +55 -0
  20. package/dist/sql-predicate-types.d.ts.map +1 -0
  21. package/dist/sql-predicate-types.js +5 -0
  22. package/dist/sql-predicate-types.js.map +1 -0
  23. package/dist/sql-predicate-zod.cjs +53 -0
  24. package/dist/sql-predicate-zod.cjs.map +6 -0
  25. package/dist/sql-predicate-zod.d.ts +11 -0
  26. package/dist/sql-predicate-zod.d.ts.map +1 -0
  27. package/dist/sql-predicate-zod.js +42 -0
  28. package/dist/sql-predicate-zod.js.map +1 -0
  29. package/dist/sql-predicate.cjs +500 -0
  30. package/dist/sql-predicate.cjs.map +6 -0
  31. package/dist/sql-predicate.d.ts +4 -0
  32. package/dist/sql-predicate.d.ts.map +1 -0
  33. package/dist/sql-predicate.js +6 -0
  34. package/dist/sql-predicate.js.map +1 -0
  35. package/package.json +35 -8
  36. package/src/index.ts +18 -0
  37. package/src/parse-sql-predicate.ts +365 -0
  38. package/src/sql-predicate-schema.ts +226 -0
  39. package/src/sql-predicate-types.ts +71 -0
  40. package/src/sql-predicate-zod.ts +49 -0
  41. package/src/sql-predicate.ts +22 -0
package/LICENSE CHANGED
@@ -24,8 +24,20 @@ THE SOFTWARE.
24
24
 
25
25
  Copyright (c) 2015 Uber Technologies, Inc.
26
26
 
27
- loaders.gl includes certain files from Cesium (https://github.com/AnalyticalGraphicsInc/cesium)
28
- under the Apache 2 License (found in the submodule: modules/3d-tiles):)
27
+ Portions of modules/images/src/lib/category-api/binary-image-api.ts are based on
28
+ binary-gltf-utils (https://github.com/Qantas94Heavy/binary-gltf-utils) under the
29
+ MIT License reproduced above.
30
+
31
+ Copyright (c) 2016-17 Karl Cheng
32
+
33
+ Portions of modules/schema-utils/src/lib/utils/async-queue.ts are adapted from
34
+ async-iter-demo (https://github.com/rauschma/async-iter-demo) under the MIT
35
+ License reproduced above.
36
+
37
+ Copyright (c) 2016 Axel Rauschmayer
38
+
39
+ loaders.gl includes certain files from Cesium (https://github.com/CesiumGS/cesium)
40
+ under the Apache 2.0 License, including files in modules/3d-tiles and modules/math.
29
41
 
30
42
  Copyright 2011-2018 CesiumJS Contributors
31
43
 
@@ -38,4 +50,3 @@ Unless required by applicable law or agreed to in writing, software
38
50
  distributed under the License is distributed on an "AS IS" BASIS,
39
51
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
40
52
  See the License for the specific language governing permissions and limitations under the License.
41
-
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # @loaders.gl/sql
2
2
 
3
3
  This module contains SQL-oriented `DataSource` implementations for external and embedded databases.
4
+ It also provides a dependency-free parser for turning a small SQL `WHERE` expression into a
5
+ portable predicate AST.
4
6
 
5
7
  ## Included sources
6
8
 
@@ -9,6 +11,17 @@ This module contains SQL-oriented `DataSource` implementations for external and
9
11
 
10
12
  ## Usage
11
13
 
14
+ Install the DuckDB runtime needed by your application in addition to `@loaders.gl/sql`:
15
+
16
+ ```bash
17
+ yarn add @duckdb/node-api
18
+ # or, for browsers
19
+ yarn add @duckdb/duckdb-wasm
20
+ ```
21
+
22
+ Both DuckDB packages are optional peers and are dynamically imported only when a DuckDB source
23
+ connects. Importing the SQL predicate parser does not load or install either runtime.
24
+
12
25
  ```ts
13
26
  import {createDataSource} from '@loaders.gl/core';
14
27
  import {DuckDBSQLSource} from '@loaders.gl/sql';
@@ -25,3 +38,39 @@ const rows = await dataSource.queryRows('SELECT * FROM numbers');
25
38
 
26
39
  Use `queryArrow()` when the backing adapter supports Arrow-native results, or when you want
27
40
  loaders.gl to convert row results into an Arrow table.
41
+
42
+ ## SQL predicate expressions
43
+
44
+ `parseSQLPredicate()` accepts the expression after `WHERE`, not a complete `SELECT` statement. It
45
+ supports comparisons, `IN`, `IS [NOT] NULL`, `AND`, `OR`, `NOT`, parentheses, scalar literals, and
46
+ named parameters.
47
+
48
+ ```ts
49
+ import {parseSQLPredicate} from '@loaders.gl/sql/sql-predicate';
50
+
51
+ const predicate = parseSQLPredicate(
52
+ "timestamp >= :start AND status IN ('valid', 'estimated')",
53
+ {parameters: {start: new Date('2026-01-01T00:00:00Z')}}
54
+ );
55
+
56
+ for await (const batch of parquetSource.read({
57
+ columns: ['timestamp', 'value'],
58
+ predicate
59
+ })) {
60
+ // SQLPredicate is structurally compatible with the experimental Parquet predicate subset.
61
+ }
62
+ ```
63
+
64
+ The dependency-free `sql-predicate` subpath does not load or traverse the optional database
65
+ adapters. The resulting `op`/`args` representation is directionally aligned with CQL2 JSON but does not
66
+ claim CQL2 conformance. `SQL_PREDICATE_JSON_SCHEMA`, `validateSQLPredicate()`, and
67
+ `isSQLPredicate()` support dependency-free payload validation.
68
+
69
+ Applications already using Zod can opt into the separate subpath without adding Zod to the root
70
+ bundle:
71
+
72
+ ```ts
73
+ import {SQLPredicateSchema} from '@loaders.gl/sql/sql-predicate-zod';
74
+
75
+ const predicate = SQLPredicateSchema.parse(untrustedPayload);
76
+ ```
@@ -6,7 +6,7 @@ import { SQLDataSource, SQL_SOURCE_DEFAULT_OPTIONS } from "./sql-source.js";
6
6
  import { convertRowsToArrowTable, convertSQLColumnsToSchema, escapeSqlString, isNodeRuntime } from "./sql-utils.js";
7
7
  // __VERSION__ is injected by babel-plugin-version-inline
8
8
  // @ts-ignore TS2304: Cannot find name '__VERSION__'.
9
- const VERSION = typeof "5.0.0-alpha.1" !== 'undefined' ? "5.0.0-alpha.1" : 'latest';
9
+ const VERSION = typeof "5.0.0-alpha.2" !== 'undefined' ? "5.0.0-alpha.2" : 'latest';
10
10
  /** DuckDB-backed SQL source. */
11
11
  export const DuckDBSQLSource = {
12
12
  dataType: null,