foxhound 2.0.26 → 2.0.28
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.
- package/README.md +27 -25
- package/docs/README.md +28 -28
- package/docs/_brand.json +18 -0
- package/docs/_cover.md +2 -2
- package/docs/_topbar.md +1 -1
- package/docs/_version.json +7 -0
- package/docs/api/README.md +14 -14
- package/docs/api/behaviorFlags.md +1 -1
- package/docs/api/buildQuery.md +2 -2
- package/docs/api/clone.md +1 -1
- package/docs/api/setScope.md +1 -1
- package/docs/architecture.md +4 -4
- package/docs/dialects/README.md +9 -9
- package/docs/dialects/postgresql.md +1 -1
- package/docs/dialects/sqlite.md +5 -5
- package/docs/index.html +6 -7
- package/docs/joins.md +3 -3
- package/docs/query/README.md +4 -4
- package/docs/query/create.md +4 -4
- package/docs/query/update.md +10 -10
- package/docs/query-overrides.md +1 -1
- package/docs/quickstart.md +6 -6
- package/docs/retold-catalog.json +245 -161
- package/docs/retold-keyword-index.json +11916 -6383
- package/docs/schema.md +33 -33
- package/docs/sorting.md +4 -4
- package/package.json +7 -6
- package/source/Foxhound-Dialects.js +1 -0
- package/source/dialects/MicrosoftSQL/FoxHound-Dialect-MSSQL.js +120 -0
- package/source/dialects/Oracle/FoxHound-Dialect-Oracle.js +1218 -0
- package/test/Foxhound-Dialect-MSSQL_tests.js +59 -4
- package/test/Foxhound-Dialect-Oracle_tests.js +463 -0
- package/docs/css/docuserve.css +0 -73
package/README.md
CHANGED
|
@@ -1,20 +1,22 @@
|
|
|
1
1
|
# FoxHound
|
|
2
2
|
|
|
3
|
+
> **[▶ Read the Foxhound Documentation](https://fable-retold.github.io/foxhound/)** — interactive docs with the full API reference.
|
|
4
|
+
|
|
3
5
|
> A fluent query generation DSL for Node.js and the browser
|
|
4
6
|
|
|
5
7
|
FoxHound is a database query builder that generates dialect-specific SQL from a single chainable API. It keeps your application code database-agnostic while producing safe, parameterized queries for MySQL, PostgreSQL, Microsoft SQL Server, SQLite, and ALASQL.
|
|
6
8
|
|
|
7
9
|
## Features
|
|
8
10
|
|
|
9
|
-
- **Chainable API**
|
|
10
|
-
- **Multiple Dialects**
|
|
11
|
-
- **Parameterized Queries**
|
|
12
|
-
- **Schema-Aware**
|
|
13
|
-
- **Full CRUD + Count**
|
|
14
|
-
- **Query Overrides**
|
|
15
|
-
- **Filtering & Sorting**
|
|
16
|
-
- **Joins & Pagination**
|
|
17
|
-
- **Fable Integration**
|
|
11
|
+
- **Chainable API** -- every configuration method returns the query object for fluent composition
|
|
12
|
+
- **Multiple Dialects** -- generate SQL for MySQL, PostgreSQL, MSSQL, SQLite, ALASQL, or plain English from the same code
|
|
13
|
+
- **Parameterized Queries** -- user-supplied values are always bound as named parameters, preventing SQL injection
|
|
14
|
+
- **Schema-Aware** -- automatic management of identity columns, timestamps, user stamps, and soft-delete tracking
|
|
15
|
+
- **Full CRUD + Count** -- build CREATE, READ, UPDATE, DELETE, UNDELETE, and COUNT queries
|
|
16
|
+
- **Query Overrides** -- underscore-style templates for custom SQL while retaining automatic parameter binding
|
|
17
|
+
- **Filtering & Sorting** -- rich filter expressions with multiple operators, logical grouping, and multi-column sorting
|
|
18
|
+
- **Joins & Pagination** -- INNER, LEFT, and custom joins plus dialect-aware LIMIT/OFFSET pagination
|
|
19
|
+
- **Fable Integration** -- operates as a Fable service, inheriting configuration, logging, and UUID generation
|
|
18
20
|
|
|
19
21
|
## Quick Start
|
|
20
22
|
|
|
@@ -55,14 +57,14 @@ FoxHound follows a configure-then-build pattern. You create a query instance, c
|
|
|
55
57
|
```
|
|
56
58
|
Application Code
|
|
57
59
|
└── FoxHound Query
|
|
58
|
-
├── setScope('Books')
|
|
59
|
-
├── addFilter('Genre', '...')
|
|
60
|
-
├── addSort('Title')
|
|
61
|
-
├── setCap(25)
|
|
62
|
-
├── setDialect('MySQL')
|
|
63
|
-
└── buildReadQuery()
|
|
64
|
-
├── query.body
|
|
65
|
-
└── query.parameters
|
|
60
|
+
├── setScope('Books') -> target table
|
|
61
|
+
├── addFilter('Genre', '...') -> WHERE clause
|
|
62
|
+
├── addSort('Title') -> ORDER BY clause
|
|
63
|
+
├── setCap(25) -> LIMIT clause
|
|
64
|
+
├── setDialect('MySQL') -> output format
|
|
65
|
+
└── buildReadQuery() -> SQL generation
|
|
66
|
+
├── query.body -> SQL string
|
|
67
|
+
└── query.parameters -> bound values
|
|
66
68
|
```
|
|
67
69
|
|
|
68
70
|
## Dialects
|
|
@@ -83,14 +85,14 @@ When a schema is attached, FoxHound automatically manages special columns:
|
|
|
83
85
|
|
|
84
86
|
| Type | Description |
|
|
85
87
|
|------|-------------|
|
|
86
|
-
| `AutoIdentity` | Auto-increment primary key
|
|
88
|
+
| `AutoIdentity` | Auto-increment primary key -- `NULL` on insert, skipped on update |
|
|
87
89
|
| `AutoGUID` | Automatically generated UUID on insert |
|
|
88
90
|
| `CreateDate` / `CreateIDUser` | Auto-populated on insert only |
|
|
89
91
|
| `UpdateDate` / `UpdateIDUser` | Auto-populated on insert and update |
|
|
90
92
|
| `DeleteDate` / `DeleteIDUser` | Auto-populated on soft delete |
|
|
91
|
-
| `Deleted` | Soft-delete flag
|
|
92
|
-
| `JSON` | Structured JSON data
|
|
93
|
-
| `JSONProxy` | JSON stored in a different SQL column
|
|
93
|
+
| `Deleted` | Soft-delete flag -- auto-filtered in reads |
|
|
94
|
+
| `JSON` | Structured JSON data -- serialized to `TEXT` on write, parsed on read |
|
|
95
|
+
| `JSONProxy` | JSON stored in a different SQL column -- uses `StorageColumn` for SQL, virtual name for objects |
|
|
94
96
|
|
|
95
97
|
## Filter Operators
|
|
96
98
|
|
|
@@ -125,7 +127,7 @@ npm run docker-dev-build
|
|
|
125
127
|
npm run docker-dev-run
|
|
126
128
|
```
|
|
127
129
|
|
|
128
|
-
3. Open http://localhost:24238/
|
|
130
|
+
3. Open http://localhost:24238/ -- the password is "retold"
|
|
129
131
|
|
|
130
132
|
## Documentation
|
|
131
133
|
|
|
@@ -137,9 +139,9 @@ npx docsify-cli serve docs
|
|
|
137
139
|
|
|
138
140
|
## Related Packages
|
|
139
141
|
|
|
140
|
-
- [meadow](https://github.com/
|
|
141
|
-
- [stricture](https://github.com/
|
|
142
|
-
- [fable](https://github.com/
|
|
142
|
+
- [meadow](https://github.com/fable-retold/meadow) - Data access and ORM
|
|
143
|
+
- [stricture](https://github.com/fable-retold/stricture) - Schema definition language
|
|
144
|
+
- [fable](https://github.com/fable-retold/fable) - Application services framework
|
|
143
145
|
|
|
144
146
|
## License
|
|
145
147
|
|
package/docs/README.md
CHANGED
|
@@ -6,15 +6,15 @@ FoxHound is a fluent query generation DSL for Node.js and the browser. It produ
|
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
9
|
-
- **Chainable API**
|
|
10
|
-
- **Multiple Dialects**
|
|
11
|
-
- **Parameterized Queries**
|
|
12
|
-
- **Schema-Aware**
|
|
13
|
-
- **Full CRUD + Count**
|
|
14
|
-
- **Query Overrides**
|
|
15
|
-
- **Filtering & Sorting**
|
|
16
|
-
- **Joins & Pagination**
|
|
17
|
-
- **Fable Integration**
|
|
9
|
+
- **Chainable API** -- every configuration method returns the query object, so you can compose queries in a single expression
|
|
10
|
+
- **Multiple Dialects** -- generate SQL for MySQL, PostgreSQL, Microsoft SQL Server, SQLite, ALASQL, or plain English, all from the same code
|
|
11
|
+
- **Parameterized Queries** -- user-supplied values are always bound as named parameters, preventing SQL injection
|
|
12
|
+
- **Schema-Aware** -- when a schema is provided, FoxHound automatically manages identity columns, timestamps, user stamps, and soft-delete tracking
|
|
13
|
+
- **Full CRUD + Count** -- build CREATE, READ, UPDATE, DELETE, UNDELETE, and COUNT queries
|
|
14
|
+
- **Query Overrides** -- supply an underscore-style template to customize query generation while still benefiting from automatic parameter binding
|
|
15
|
+
- **Filtering & Sorting** -- rich filter expressions with multiple operators, logical grouping, and multi-column sorting
|
|
16
|
+
- **Joins & Pagination** -- INNER, LEFT, and custom joins plus dialect-aware LIMIT/OFFSET pagination
|
|
17
|
+
- **Fable Integration** -- operates as a Fable service, inheriting configuration, logging, and UUID generation
|
|
18
18
|
|
|
19
19
|
## Quick Start
|
|
20
20
|
|
|
@@ -48,33 +48,33 @@ console.log(tmpQuery.query.parameters);
|
|
|
48
48
|
|
|
49
49
|
## How It Works
|
|
50
50
|
|
|
51
|
-
1. **Create a Query**
|
|
52
|
-
2. **Configure**
|
|
53
|
-
3. **Set a Dialect**
|
|
54
|
-
4. **Build**
|
|
55
|
-
5. **Execute**
|
|
51
|
+
1. **Create a Query** -- instantiate via `foxhound.new(fable)` or through a Fable service
|
|
52
|
+
2. **Configure** -- chain methods to set scope (table), fields, filters, sorts, joins, and pagination
|
|
53
|
+
3. **Set a Dialect** -- call `.setDialect('MySQL')` (or PostgreSQL, MSSQL, SQLite, ALASQL, English)
|
|
54
|
+
4. **Build** -- call a build method such as `.buildReadQuery()` to generate the SQL
|
|
55
|
+
5. **Execute** -- read the generated SQL from `.query.body` and bound parameters from `.query.parameters`
|
|
56
56
|
|
|
57
57
|
## Documentation
|
|
58
58
|
|
|
59
|
-
- [Quickstart](quickstart.md)
|
|
60
|
-
- [Architecture](architecture.md)
|
|
61
|
-
- [Filters](filters.md)
|
|
62
|
-
- [Sorting](sorting.md)
|
|
63
|
-
- [Joins](joins.md)
|
|
64
|
-
- [Pagination](pagination.md)
|
|
65
|
-
- [Schema Integration](schema.md)
|
|
66
|
-
- [Dialects](dialects/README.md)
|
|
67
|
-
- [API Reference](api/README.md)
|
|
68
|
-
- [Query Overrides](query-overrides.md)
|
|
59
|
+
- [Quickstart](quickstart.md) -- get up and running in five minutes
|
|
60
|
+
- [Architecture](architecture.md) -- understand FoxHound's internal design
|
|
61
|
+
- [Filters](filters.md) -- filter operators and logical grouping
|
|
62
|
+
- [Sorting](sorting.md) -- ORDER BY clause generation
|
|
63
|
+
- [Joins](joins.md) -- multi-table queries
|
|
64
|
+
- [Pagination](pagination.md) -- LIMIT/OFFSET across dialects
|
|
65
|
+
- [Schema Integration](schema.md) -- automatic column management
|
|
66
|
+
- [Dialects](dialects/README.md) -- dialect-specific features and differences
|
|
67
|
+
- [API Reference](api/README.md) -- complete function reference with code examples
|
|
68
|
+
- [Query Overrides](query-overrides.md) -- custom SQL templates
|
|
69
69
|
|
|
70
70
|
## Related Packages
|
|
71
71
|
|
|
72
72
|
| Package | Purpose |
|
|
73
73
|
|---------|---------|
|
|
74
|
-
| [fable](https://github.com/
|
|
75
|
-
| [meadow](https://github.com/
|
|
76
|
-
| [stricture](https://github.com/
|
|
77
|
-
| [meadow-endpoints](https://github.com/
|
|
74
|
+
| [fable](https://github.com/fable-retold/fable) | Core service framework (required dependency) |
|
|
75
|
+
| [meadow](https://github.com/fable-retold/meadow) | Data access layer that uses FoxHound for query generation |
|
|
76
|
+
| [stricture](https://github.com/fable-retold/stricture) | Schema definition tool that produces FoxHound-compatible schema arrays |
|
|
77
|
+
| [meadow-endpoints](https://github.com/fable-retold/meadow-endpoints) | REST endpoint generator built on Meadow + FoxHound |
|
|
78
78
|
|
|
79
79
|
## Testing
|
|
80
80
|
|
package/docs/_brand.json
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"Hash": "foxhound",
|
|
3
|
+
"Name": "Foxhound",
|
|
4
|
+
"Tagline": "Fluent query DSL generating dialect-specific queries for MySQL, MSSQL, SQLite, ALASQL, and MongoDB",
|
|
5
|
+
"Palette": "mix",
|
|
6
|
+
"Icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"frame-foxhound-filled-light\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\" fill=\"#b69d35\"/>\n\t\t<g clip-path=\"url(#frame-foxhound-filled-light)\"><path d=\"M 48.00,12.00 L 79.18,30.00 L 79.18,66.00 L 48.00,84.00 L 16.82,66.00 L 16.82,30.00 Z\" fill=\"#70c0b6\"/>\n\t\t\t\t\t<circle cx=\"48\" cy=\"48\" r=\"24\" fill=\"rgba(255,255,255,0.18)\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"56\" font-weight=\"700\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">F</text>\n\t</svg>",
|
|
7
|
+
"IconType": "svg",
|
|
8
|
+
"Favicon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-foxhound-light\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\" fill=\"#b69d35\"/>\n\t\t<g clip-path=\"url(#fav-foxhound-light)\"><path d=\"M 48.00,12.00 L 79.18,30.00 L 79.18,66.00 L 48.00,84.00 L 16.82,66.00 L 16.82,30.00 Z\" fill=\"#70c0b6\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">F</text>\n\t</svg>",
|
|
9
|
+
"FaviconDark": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-foxhound-dark\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\" fill=\"#d0bf77\"/>\n\t\t<g clip-path=\"url(#fav-foxhound-dark)\"><path d=\"M 48.00,12.00 L 79.18,30.00 L 79.18,66.00 L 48.00,84.00 L 16.82,66.00 L 16.82,30.00 Z\" fill=\"#b3d8d4\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#101418\" letter-spacing=\"-1\">F</text>\n\t</svg>",
|
|
10
|
+
"Colors": {
|
|
11
|
+
"Primary": "#b69d35",
|
|
12
|
+
"Secondary": "#70c0b6",
|
|
13
|
+
"PrimaryLight": "#b69d35",
|
|
14
|
+
"PrimaryDark": "#d0bf77",
|
|
15
|
+
"SecondaryLight": "#70c0b6",
|
|
16
|
+
"SecondaryDark": "#b3d8d4"
|
|
17
|
+
}
|
|
18
|
+
}
|
package/docs/_cover.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# FoxHound
|
|
1
|
+
# FoxHound
|
|
2
2
|
|
|
3
3
|
> A fluent query generation DSL for Node.js and the browser
|
|
4
4
|
|
|
@@ -9,4 +9,4 @@
|
|
|
9
9
|
|
|
10
10
|
[Get Started](quickstart.md)
|
|
11
11
|
[API Reference](api/README.md)
|
|
12
|
-
[GitHub](https://github.com/
|
|
12
|
+
[GitHub](https://github.com/fable-retold/foxhound)
|
package/docs/_topbar.md
CHANGED
package/docs/api/README.md
CHANGED
|
@@ -20,30 +20,30 @@ These methods configure the query and return `this` for chaining.
|
|
|
20
20
|
|
|
21
21
|
| Method | Purpose |
|
|
22
22
|
|--------|---------|
|
|
23
|
-
| [setScope(pScope)](
|
|
24
|
-
| [setDialect(pDialectName)](
|
|
25
|
-
| [setDataElements(pDataElements)](
|
|
26
|
-
| [setDistinct(pDistinct)](
|
|
27
|
-
| [addFilter / setFilter](
|
|
28
|
-
| [addSort / setSort](
|
|
29
|
-
| [addJoin / setJoin](
|
|
30
|
-
| [setCap / setBegin](
|
|
31
|
-
| [addRecord(pRecord)](
|
|
32
|
-
| [setIDUser(pIDUser)](
|
|
33
|
-
| [Behavior Flags](
|
|
23
|
+
| [setScope(pScope)](setScope.md) | Set the target table or collection |
|
|
24
|
+
| [setDialect(pDialectName)](setDialect.md) | Set the SQL dialect for output |
|
|
25
|
+
| [setDataElements(pDataElements)](setDataElements.md) | Set which columns to select |
|
|
26
|
+
| [setDistinct(pDistinct)](setDistinct.md) | Enable DISTINCT results |
|
|
27
|
+
| [addFilter / setFilter](addFilter.md) | Add or set WHERE clause conditions |
|
|
28
|
+
| [addSort / setSort](addSort.md) | Add or set ORDER BY expressions |
|
|
29
|
+
| [addJoin / setJoin](addJoin.md) | Add or set JOIN expressions |
|
|
30
|
+
| [setCap / setBegin](setCap.md) | Set pagination (LIMIT / OFFSET) |
|
|
31
|
+
| [addRecord(pRecord)](addRecord.md) | Add a record for INSERT or UPDATE |
|
|
32
|
+
| [setIDUser(pIDUser)](setIDUser.md) | Set the user ID for audit columns |
|
|
33
|
+
| [Behavior Flags](behaviorFlags.md) | Disable auto-identity, timestamps, user stamps, delete tracking |
|
|
34
34
|
|
|
35
35
|
### Query Building
|
|
36
36
|
|
|
37
37
|
| Method | Purpose |
|
|
38
38
|
|--------|---------|
|
|
39
|
-
| [Build Methods](
|
|
39
|
+
| [Build Methods](buildQuery.md) | buildCreateQuery, buildReadQuery, buildUpdateQuery, buildDeleteQuery, buildUndeleteQuery, buildCountQuery |
|
|
40
40
|
|
|
41
41
|
### Utility
|
|
42
42
|
|
|
43
43
|
| Method | Purpose |
|
|
44
44
|
|--------|---------|
|
|
45
|
-
| [clone / resetParameters / mergeParameters](
|
|
46
|
-
| [Query Overrides](
|
|
45
|
+
| [clone / resetParameters / mergeParameters](clone.md) | Copy, reset, or merge query state |
|
|
46
|
+
| [Query Overrides](queryOverrides.md) | Custom SQL templates for Read and Count |
|
|
47
47
|
|
|
48
48
|
## Properties
|
|
49
49
|
|
|
@@ -120,4 +120,4 @@ tmpQuery
|
|
|
120
120
|
.setDisableDeleteTracking(true);
|
|
121
121
|
```
|
|
122
122
|
|
|
123
|
-
This gives you full manual control over all column values
|
|
123
|
+
This gives you full manual control over all column values -- useful for data migration or import scenarios.
|
package/docs/api/buildQuery.md
CHANGED
|
@@ -89,7 +89,7 @@ Generate a soft-delete UPDATE or a hard DELETE.
|
|
|
89
89
|
When a schema has a `Deleted` column type and delete tracking is enabled:
|
|
90
90
|
|
|
91
91
|
```javascript
|
|
92
|
-
// Soft delete
|
|
92
|
+
// Soft delete -- generates an UPDATE
|
|
93
93
|
tmpQuery.buildDeleteQuery();
|
|
94
94
|
// => UPDATE `Books` SET Deleted = 1, DeleteDate = NOW(3), ...
|
|
95
95
|
```
|
|
@@ -97,7 +97,7 @@ tmpQuery.buildDeleteQuery();
|
|
|
97
97
|
When no schema or delete tracking is disabled:
|
|
98
98
|
|
|
99
99
|
```javascript
|
|
100
|
-
// Hard delete
|
|
100
|
+
// Hard delete -- generates a DELETE
|
|
101
101
|
tmpQuery.setDisableDeleteTracking(true).buildDeleteQuery();
|
|
102
102
|
// => DELETE FROM `Books` WHERE IDBook = :IDBook_w0;
|
|
103
103
|
```
|
package/docs/api/clone.md
CHANGED
|
@@ -18,7 +18,7 @@ Returns a new FoxHound query instance with copies of the current scope, begin, c
|
|
|
18
18
|
|
|
19
19
|
### Description
|
|
20
20
|
|
|
21
|
-
Cloning is useful when you need to build multiple similar queries from the same base configuration. The cloned query has its own independent state
|
|
21
|
+
Cloning is useful when you need to build multiple similar queries from the same base configuration. The cloned query has its own independent state -- changes to the clone do not affect the original.
|
|
22
22
|
|
|
23
23
|
### Example
|
|
24
24
|
|
package/docs/api/setScope.md
CHANGED
|
@@ -20,7 +20,7 @@ Returns `this` for chaining.
|
|
|
20
20
|
|
|
21
21
|
## Description
|
|
22
22
|
|
|
23
|
-
The scope defines which table (or collection, in NoSQL dialects) the query targets. This is required for all query types
|
|
23
|
+
The scope defines which table (or collection, in NoSQL dialects) the query targets. This is required for all query types -- it appears as the `FROM` clause in SELECT, `INSERT INTO` in CREATE, `UPDATE` in UPDATE, and `DELETE FROM` in DELETE.
|
|
24
24
|
|
|
25
25
|
FoxHound validates that the input is a string. Non-string values are ignored and an error is logged.
|
|
26
26
|
|
package/docs/architecture.md
CHANGED
|
@@ -168,10 +168,10 @@ tmpQuery
|
|
|
168
168
|
|
|
169
169
|
FoxHound depends on Fable for:
|
|
170
170
|
|
|
171
|
-
- **UUID Generation**
|
|
172
|
-
- **Logging**
|
|
173
|
-
- **Utility Functions**
|
|
174
|
-
- **Configuration**
|
|
171
|
+
- **UUID Generation** -- each query and record gets a unique identifier via `_Fable.getUUID()`
|
|
172
|
+
- **Logging** -- filter, scope, and query errors are logged through `_Fable.log`
|
|
173
|
+
- **Utility Functions** -- `_Fable.Utility.extend()` for parameter merging and `_Fable.Utility.template()` for query overrides
|
|
174
|
+
- **Configuration** -- inherits any relevant settings from the Fable config
|
|
175
175
|
|
|
176
176
|
## Schema-Aware Generation
|
|
177
177
|
|
package/docs/dialects/README.md
CHANGED
|
@@ -6,11 +6,11 @@ FoxHound uses a dialect strategy pattern to generate database-specific SQL from
|
|
|
6
6
|
|
|
7
7
|
| Dialect | Target | Identifier Quoting | Parameter Prefix | Pagination |
|
|
8
8
|
|---------|--------|-------------------|-----------------|------------|
|
|
9
|
-
| [MySQL](
|
|
10
|
-
| [PostgreSQL](
|
|
11
|
-
| [MSSQL](
|
|
12
|
-
| [SQLite](
|
|
13
|
-
| [ALASQL](
|
|
9
|
+
| [MySQL](mysql.md) | MySQL / MariaDB | `` `backticks` `` | `:name` | `LIMIT offset, count` |
|
|
10
|
+
| [PostgreSQL](postgresql.md) | PostgreSQL 9.5+ | `"double quotes"` | `:name` | `LIMIT count OFFSET offset` |
|
|
11
|
+
| [MSSQL](mssql.md) | Microsoft SQL Server | `[brackets]` | `@name` | `OFFSET n ROWS FETCH NEXT m ROWS ONLY` |
|
|
12
|
+
| [SQLite](sqlite.md) | SQLite 3 | `` `backticks` `` | `:name` | `LIMIT count OFFSET offset` |
|
|
13
|
+
| [ALASQL](alasql.md) | ALASQL (in-memory) | `` `backticks` `` | `:name` | `LIMIT count FETCH offset` |
|
|
14
14
|
| English | Human-readable | none | none | prose |
|
|
15
15
|
| MeadowEndpoints | REST URL generation | none | none | query string |
|
|
16
16
|
|
|
@@ -45,10 +45,10 @@ Each method receives the full Parameters object and returns a SQL string (or `fa
|
|
|
45
45
|
|
|
46
46
|
All SQL dialects share these behaviors:
|
|
47
47
|
|
|
48
|
-
- **Parameterized values**
|
|
49
|
-
- **Schema-aware column management**
|
|
50
|
-
- **Soft-delete filtering**
|
|
51
|
-
- **Query overrides**
|
|
48
|
+
- **Parameterized values** -- user data is always bound as named parameters, never interpolated
|
|
49
|
+
- **Schema-aware column management** -- AutoIdentity, timestamps, user stamps, and soft-delete columns are handled automatically based on schema type annotations
|
|
50
|
+
- **Soft-delete filtering** -- Read and Count queries automatically exclude rows where the `Deleted` column is `1` (when schema is present)
|
|
51
|
+
- **Query overrides** -- Read and Count queries support underscore templates for custom SQL generation
|
|
52
52
|
|
|
53
53
|
## Choosing a Dialect
|
|
54
54
|
|
|
@@ -56,7 +56,7 @@ INSERT INTO "Books" ( "IDBook", "Title") VALUES ( DEFAULT, :Title_1) RETURNING *
|
|
|
56
56
|
|
|
57
57
|
## RETURNING Clause
|
|
58
58
|
|
|
59
|
-
All INSERT statements include `RETURNING *`, which returns the full inserted row
|
|
59
|
+
All INSERT statements include `RETURNING *`, which returns the full inserted row -- including any auto-generated values like serial IDs and default timestamps.
|
|
60
60
|
|
|
61
61
|
## Joins
|
|
62
62
|
|
package/docs/dialects/sqlite.md
CHANGED
|
@@ -10,7 +10,7 @@ SQLite uses backtick quoting for identifiers to avoid conflicts with SQLite's ma
|
|
|
10
10
|
SELECT * FROM Books WHERE `Genre` = :Genre_w0;
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
Table names are not quoted in the SQLite dialect
|
|
13
|
+
Table names are not quoted in the SQLite dialect -- they are used as plain identifiers.
|
|
14
14
|
|
|
15
15
|
## Named Parameters
|
|
16
16
|
|
|
@@ -49,7 +49,7 @@ SELECT COUNT(DISTINCT IDBook) AS RowCount FROM Books;
|
|
|
49
49
|
|
|
50
50
|
## Soft Delete
|
|
51
51
|
|
|
52
|
-
Works the same as other dialects
|
|
52
|
+
Works the same as other dialects -- when a `Deleted` column is present in the schema, Delete generates an UPDATE:
|
|
53
53
|
|
|
54
54
|
```sql
|
|
55
55
|
UPDATE Books SET `Deleted` = 1, `DeleteDate` = NOW(),
|
|
@@ -63,9 +63,9 @@ The `NOW()` calls are replaced with `datetime('now')` by the Meadow SQLite provi
|
|
|
63
63
|
|
|
64
64
|
When using the Meadow SQLite provider with `better-sqlite3`:
|
|
65
65
|
|
|
66
|
-
- **Boolean coercion**
|
|
67
|
-
- **Undefined coercion**
|
|
68
|
-
- **Synchronous execution**
|
|
66
|
+
- **Boolean coercion** -- `better-sqlite3` only accepts numbers, strings, bigints, buffers, and null. The provider automatically converts boolean values (`true`/`false`) to integers (`1`/`0`)
|
|
67
|
+
- **Undefined coercion** -- undefined values are converted to `null`
|
|
68
|
+
- **Synchronous execution** -- `better-sqlite3` is synchronous, but the Meadow provider wraps calls in an async-compatible callback pattern
|
|
69
69
|
|
|
70
70
|
## Query Overrides
|
|
71
71
|
|
package/docs/index.html
CHANGED
|
@@ -4,12 +4,10 @@
|
|
|
4
4
|
<meta charset="utf-8">
|
|
5
5
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
6
6
|
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
|
|
7
|
-
<meta name="description" content="Documentation
|
|
7
|
+
<meta name="description" content="FoxHound v2.0.27 Documentation — A Database Query generation library.">
|
|
8
8
|
|
|
9
|
-
<title>Documentation</title>
|
|
9
|
+
<title>FoxHound v2.0.27 Documentation</title>
|
|
10
10
|
|
|
11
|
-
<!-- Application Stylesheet -->
|
|
12
|
-
<link href="css/docuserve.css" rel="stylesheet">
|
|
13
11
|
<!-- KaTeX stylesheet for LaTeX equation rendering -->
|
|
14
12
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
|
|
15
13
|
<!-- PICT Dynamic View CSS Container -->
|
|
@@ -28,12 +26,13 @@
|
|
|
28
26
|
<!-- The root container for the Pict application -->
|
|
29
27
|
<div id="Docuserve-Application-Container"></div>
|
|
30
28
|
|
|
31
|
-
<!-- Mermaid diagram rendering
|
|
29
|
+
<!-- Mermaid diagram rendering. pict-section-content (v0.1.8+) drives
|
|
30
|
+
initialization with theme: 'base' + themeVariables sourced
|
|
31
|
+
from --theme-color-* so diagrams follow the active theme. -->
|
|
32
32
|
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
|
|
33
|
-
<script>mermaid.initialize({ startOnLoad: false, theme: 'default' });</script>
|
|
34
33
|
<!-- KaTeX for LaTeX equation rendering -->
|
|
35
34
|
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>
|
|
36
35
|
<!-- Load the Docuserve PICT Application Bundle from jsDelivr CDN -->
|
|
37
|
-
<script src="https://cdn.jsdelivr.net/npm/pict-docuserve@
|
|
36
|
+
<script src="https://cdn.jsdelivr.net/npm/pict-docuserve@1/dist/pict-docuserve.min.js" type="text/javascript"></script>
|
|
38
37
|
</body>
|
|
39
38
|
</html>
|
package/docs/joins.md
CHANGED
|
@@ -94,8 +94,8 @@ Invalid joins are logged as warnings and silently skipped.
|
|
|
94
94
|
|
|
95
95
|
## Dialect Differences
|
|
96
96
|
|
|
97
|
-
- **MySQL**
|
|
98
|
-
- **MSSQL**
|
|
99
|
-
- **SQLite/ALASQL**
|
|
97
|
+
- **MySQL** -- `INNER JOIN Authors ON Authors.IDAuthor = Books.IDAuthor`
|
|
98
|
+
- **MSSQL** -- `INNER JOIN [Authors] ON Authors.IDAuthor = Books.IDAuthor`
|
|
99
|
+
- **SQLite/ALASQL** -- joins are supported in Read queries but not generated (the SQLite and ALASQL dialects do not include a `generateJoins` function; joins work through query overrides)
|
|
100
100
|
|
|
101
101
|
> **Note:** The SQLite and ALASQL dialects are primarily designed for simpler single-table queries. For complex join scenarios, consider using a query override or the MySQL/MSSQL dialect.
|
package/docs/query/README.md
CHANGED
|
@@ -8,9 +8,9 @@ FoxHound builds queries through a two-phase process: **configure** then **build*
|
|
|
8
8
|
Configure ──► Build ──► Access Results
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
1. **Configure**
|
|
12
|
-
2. **Build**
|
|
13
|
-
3. **Access**
|
|
11
|
+
1. **Configure** -- set the scope, fields, filters, sorts, joins, pagination, records, and dialect
|
|
12
|
+
2. **Build** -- call one of the `build*Query()` methods to generate the SQL
|
|
13
|
+
3. **Access** -- read `query.body` for the SQL string and `query.parameters` for bound values
|
|
14
14
|
|
|
15
15
|
## Creating a Query Instance
|
|
16
16
|
|
|
@@ -84,7 +84,7 @@ After a query is built, you can reset the parameters for reuse or clone the quer
|
|
|
84
84
|
// Reset to default parameters
|
|
85
85
|
tmpQuery.resetParameters();
|
|
86
86
|
|
|
87
|
-
// Clone
|
|
87
|
+
// Clone -- copies scope, begin, cap, schema, filters, sorts, and dataElements
|
|
88
88
|
var tmpClone = tmpQuery.clone();
|
|
89
89
|
```
|
|
90
90
|
|
package/docs/query/create.md
CHANGED
|
@@ -60,7 +60,7 @@ tmpQuery.setDisableDeleteTracking(true); // Include delete columns on insert
|
|
|
60
60
|
|
|
61
61
|
The INSERT syntax is largely the same across dialects, with a few differences:
|
|
62
62
|
|
|
63
|
-
- **MySQL**
|
|
64
|
-
- **MSSQL**
|
|
65
|
-
- **SQLite**
|
|
66
|
-
- **ALASQL**
|
|
63
|
+
- **MySQL** -- uses backtick-quoted identifiers and `:name` parameters
|
|
64
|
+
- **MSSQL** -- uses bracket-quoted identifiers, `@name` parameters, and skips the AutoIdentity column entirely (rather than inserting NULL)
|
|
65
|
+
- **SQLite** -- uses backtick-quoted identifiers and `:name` parameters
|
|
66
|
+
- **ALASQL** -- same as SQLite
|
package/docs/query/update.md
CHANGED
|
@@ -27,13 +27,13 @@ When a schema is present, FoxHound manages certain columns automatically:
|
|
|
27
27
|
|
|
28
28
|
| Schema Type | Behavior on Update |
|
|
29
29
|
|------------|-------------------|
|
|
30
|
-
| `AutoIdentity` | **Skipped**
|
|
31
|
-
| `CreateDate` | **Skipped**
|
|
32
|
-
| `CreateIDUser` | **Skipped**
|
|
30
|
+
| `AutoIdentity` | **Skipped** -- never updated |
|
|
31
|
+
| `CreateDate` | **Skipped** -- set only on insert |
|
|
32
|
+
| `CreateIDUser` | **Skipped** -- set only on insert |
|
|
33
33
|
| `UpdateDate` | Set to current timestamp automatically |
|
|
34
34
|
| `UpdateIDUser` | Set to the value from `setIDUser()` |
|
|
35
|
-
| `DeleteDate` | **Skipped**
|
|
36
|
-
| `DeleteIDUser` | **Skipped**
|
|
35
|
+
| `DeleteDate` | **Skipped** -- managed by delete operations |
|
|
36
|
+
| `DeleteIDUser` | **Skipped** -- managed by delete operations |
|
|
37
37
|
|
|
38
38
|
## Disabling Auto-Management
|
|
39
39
|
|
|
@@ -44,13 +44,13 @@ tmpQuery.setDisableAutoUserStamp(true); // Don't auto-set UpdateIDUser
|
|
|
44
44
|
|
|
45
45
|
## Important Notes
|
|
46
46
|
|
|
47
|
-
- The record passed to `addRecord()` should contain only the columns you want to change
|
|
47
|
+
- The record passed to `addRecord()` should contain only the columns you want to change -- FoxHound generates SET clauses for each key in the record object
|
|
48
48
|
- Always include a filter (usually on the primary key) to avoid updating all rows
|
|
49
49
|
- If the record object is empty or no records have been added, `buildUpdateQuery()` returns `false` for the query body
|
|
50
50
|
|
|
51
51
|
## Dialect Differences
|
|
52
52
|
|
|
53
|
-
- **MySQL**
|
|
54
|
-
- **MSSQL**
|
|
55
|
-
- **SQLite**
|
|
56
|
-
- **ALASQL**
|
|
53
|
+
- **MySQL** -- backtick-quoted identifiers, `:name` parameters
|
|
54
|
+
- **MSSQL** -- bracket-quoted identifiers, `@name` parameters; special handling for `UpdateDate` with `disableAutoDateStamp`
|
|
55
|
+
- **SQLite** -- backtick-quoted identifiers, `:name` parameters
|
|
56
|
+
- **ALASQL** -- same as SQLite
|
package/docs/query-overrides.md
CHANGED
|
@@ -85,4 +85,4 @@ Query overrides are useful when you need:
|
|
|
85
85
|
- `UNION` queries
|
|
86
86
|
- Any SQL feature not directly supported by FoxHound's fluent API
|
|
87
87
|
|
|
88
|
-
For straightforward CRUD operations, the standard query builders are preferred
|
|
88
|
+
For straightforward CRUD operations, the standard query builders are preferred -- they are safer and more portable across dialects.
|
package/docs/quickstart.md
CHANGED
|
@@ -8,7 +8,7 @@ Get up and running with FoxHound in under five minutes.
|
|
|
8
8
|
npm install foxhound fable
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
FoxHound requires [Fable](https://github.com/
|
|
11
|
+
FoxHound requires [Fable](https://github.com/fable-retold/fable) as a peer dependency for logging, UUID generation, and utility functions.
|
|
12
12
|
|
|
13
13
|
## Your First Query
|
|
14
14
|
|
|
@@ -189,8 +189,8 @@ console.log(tmpQuery.query.body);
|
|
|
189
189
|
|
|
190
190
|
## Next Steps
|
|
191
191
|
|
|
192
|
-
- [Architecture](architecture.md)
|
|
193
|
-
- [Filters](filters.md)
|
|
194
|
-
- [Schema Integration](schema.md)
|
|
195
|
-
- [Dialects](dialects/README.md)
|
|
196
|
-
- [API Reference](api/README.md)
|
|
192
|
+
- [Architecture](architecture.md) -- understand FoxHound's internal design
|
|
193
|
+
- [Filters](filters.md) -- learn about filter operators and grouping
|
|
194
|
+
- [Schema Integration](schema.md) -- use schemas for automatic column management
|
|
195
|
+
- [Dialects](dialects/README.md) -- explore dialect-specific features
|
|
196
|
+
- [API Reference](api/README.md) -- complete function reference
|