@oino-ts/hashid 1.0.8 → 1.1.0
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 +70 -44
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -9,47 +9,69 @@ return new Response(result.modelset.writeString(OINOContentType.json))
|
|
|
9
9
|
|
|
10
10
|
# GETTING STARTED
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
12
|
+
## Create Datasources
|
|
13
|
+
|
|
14
|
+
### Create an SQL DB
|
|
15
|
+
|
|
16
|
+
First install the `@oino-ts/db` npm package and necessary database packages and import them in your code.
|
|
14
17
|
```
|
|
15
18
|
bun install @oino-ts/db
|
|
16
19
|
bun install @oino-ts/db-bunsqlite
|
|
17
20
|
```
|
|
18
21
|
|
|
19
22
|
```
|
|
20
|
-
import { OINODb,
|
|
23
|
+
import { OINODb, OINODbFactory } from "@oino-ts/db";
|
|
24
|
+
import { OINOApi } from "@oino-ts/db";
|
|
21
25
|
import { OINODbBunSqlite } from "@oino-ts/db-bunsqlite"
|
|
22
26
|
```
|
|
23
27
|
|
|
24
|
-
|
|
25
|
-
Register your database implementation and logger (see [`OINOConsoleLog`](https://pragmatta.github.io/oino-ts/classes/common_src.OINOConsoleLog.html) how to implement your own)
|
|
28
|
+
Next register your database implementation and logger (see [`OINOConsoleLog`](https://pragmatta.github.io/oino-ts/classes/common_src.OINOConsoleLog.html) how to implement your own)
|
|
26
29
|
|
|
27
30
|
```
|
|
28
31
|
OINOLog.setLogger(new OINOConsoleLog())
|
|
29
|
-
|
|
32
|
+
OINODbFactory.registerDb("OINODbBunSqlite", OINODbBunSqlite)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Finally creating a database connection [`OINODb`](https://pragmatta.github.io/oino-ts/classes/db_src.OINODb.html) is done by passing [`OINODbParams`](https://pragmatta.github.io/oino-ts/types/db_src.OINODbParams.html) to the factory method. For [`OINODbBunSqlite`](https://pragmatta.github.io/oino-ts/classes/db_bunsqlite_src.OINODbBunSqlite.html) that means a file url for the database file, for others network host, port, credentials etc.
|
|
36
|
+
```
|
|
37
|
+
const db:OINODb = await OINODbFactory.createDb( { type: "OINODbBunSqlite", url: "file://../localDb/northwind.sqlite" } )
|
|
30
38
|
```
|
|
31
39
|
|
|
32
|
-
### Create
|
|
33
|
-
Creating
|
|
40
|
+
### Create NoSQL datasources
|
|
41
|
+
Creating NoSQL datasources works similarly by importing the [`OINONoSql`](https://pragmatta.github.io/oino-ts/modules/nosql_src.html) package and either the [`OINONoSqlAws`](https://pragmatta.github.io/oino-ts/modules/nosql-aws_src.html) or [`OINONoSqlAzure`](https://pragmatta.github.io/oino-ts/modules/nosql-azure_src.html), registering the implementation with the factory
|
|
42
|
+
```
|
|
43
|
+
OINONoSqlFactory.registerNoSql("OINONoSqlAzureTable", OINONoSqlAzureTable)
|
|
44
|
+
const nosql_azure_params = { type: "OINONoSqlAzureTable", table: "NorthwindOrders", credentials: { connectionStr: process.env.OINOCLOUD_TEST_BLOB_AZURE_CONSTR } }
|
|
45
|
+
const nosql_azure = await OINONoSqlFactory.createNoSql(nosql_azure_params)
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
NOTE! Format of the credentials varies by platform and might require extra authorization.
|
|
49
|
+
|
|
50
|
+
### Create Blob datasources
|
|
51
|
+
Creating Blob datasources works similarly by importing the [`OINOBlob`](https://pragmatta.github.io/oino-ts/classes/blob_src.OINOBlob.html) package and either the [`OINOBlobAws`](https://pragmatta.github.io/oino-ts/modules/blob-aws_src.html) or [`OINOBlobAzure`](https://pragmatta.github.io/oino-ts/modules/blob-azure_src.html), registering the implementation with the factory
|
|
34
52
|
```
|
|
35
|
-
|
|
53
|
+
OINOBlobFactory.registerBlob("OINOBlobAzureTable", OINOBlobAzureTable)
|
|
54
|
+
const Blob_azure_params = { type: "OINOBlobAzureTable", table: "NorthwindOrders", credentials: { connectionStr: process.env.OINOCLOUD_TEST_BLOB_AZURE_CONSTR } }
|
|
55
|
+
const Blob_azure = await OINOBlobFactory.createBlob(nosql_azure_params)
|
|
36
56
|
```
|
|
37
57
|
|
|
38
|
-
|
|
39
|
-
|
|
58
|
+
NOTE! Format of the credentials varies by platform and might require extra authorization.
|
|
59
|
+
|
|
60
|
+
## Create an API
|
|
61
|
+
From a datasource you can create an [`OINOApi`](https://pragmatta.github.io/oino-ts/classes/db_src.OINODbApi.html) by passing [`OINOApiParams`](https://pragmatta.github.io/oino-ts/types/db_src.OINODbApiParams.html) with table name and preferences to the factory method.
|
|
40
62
|
```
|
|
41
63
|
const api_employees:OINOApi = await OINOFactory.createApi(db, { tableName: "Employees", excludeFields:["BirthDate"] })
|
|
42
64
|
```
|
|
43
65
|
|
|
44
|
-
|
|
66
|
+
## Pass HTTP requests to API
|
|
45
67
|
When you receive a HTTP request, just pass the method, URL ID, body and params to the correct API, which will parse and validate input and return results.
|
|
46
68
|
|
|
47
69
|
```
|
|
48
70
|
const result:OINOApiResult = await api_orderdetails.doRequest("GET", id, body, params)
|
|
49
71
|
```
|
|
50
72
|
|
|
51
|
-
|
|
52
|
-
The results for a GET request will contain [`OINOModelSet`](https://pragmatta.github.io/oino-ts/classes/
|
|
73
|
+
## Write results back to HTTP Response
|
|
74
|
+
The results for a GET request will contain [`OINOModelSet`](https://pragmatta.github.io/oino-ts/classes/common_src.OINOModelSet.html) data that can be written out as JSON or CSV as needed. For other requests result is just success or error with messages.
|
|
53
75
|
```
|
|
54
76
|
return new Response(result.data.writeString(OINOContentType.json))
|
|
55
77
|
```
|
|
@@ -90,20 +112,29 @@ OINO handles serialization of data to JSON/CSV/etc. and back based on the data m
|
|
|
90
112
|
- Multiple lines could be used to post multiple rows.
|
|
91
113
|
|
|
92
114
|
|
|
93
|
-
##
|
|
94
|
-
OINO functions as a
|
|
115
|
+
## Datasource Abstraction
|
|
116
|
+
OINO functions as a datasource abstraction for SQL, NoSQL and Blob storages, providing a consistent interface for working with different datasources. It abstracts out different conventions in connecting, making queries and formatting data.
|
|
95
117
|
|
|
96
|
-
Currently supported
|
|
97
|
-
-
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
-
|
|
118
|
+
Currently supported datasources:
|
|
119
|
+
- SQL
|
|
120
|
+
- Bun Sqlite through Bun native implementation
|
|
121
|
+
- Postgresql through [pg](https://www.npmjs.com/package/pg)-package
|
|
122
|
+
- Mariadb / Mysql-support through [mariadb](https://www.npmjs.com/package/mariadb)-package
|
|
123
|
+
- Sql Server through [mssql](https://www.npmjs.com/package/mssql)-package
|
|
124
|
+
- NoSQL
|
|
125
|
+
- AWS DynamoDb through [@aws-sdk/client-dynamodb](https://www.npmjs.com/package/@aws-sdk/client-dynamodb)-package
|
|
126
|
+
- Azure Tables through [@azure/data-tables](https://www.npmjs.com/package/@azure/data-tables)-package
|
|
127
|
+
- Blob
|
|
128
|
+
- AWS S3 through [@aws-sdk/client-s3](https://www.npmjs.com/package/@aws-sdk/client-s3)-package
|
|
129
|
+
- Azure Blobs through [@azure/storage-blob](https://www.npmjs.com/package/@azure/storage-blob)-package
|
|
101
130
|
|
|
102
131
|
## Composite Keys
|
|
103
132
|
To support tables with multipart primary keys OINO generates a composite key `_OINOID_` that is included in the result and can be used as the REST ID. For example in the example above table `OrderDetails` has two primary keys `OrderID` and `ProductID` making the `_OINOID_` of form `11077:99`.
|
|
104
133
|
|
|
105
134
|
## Power Of SQL
|
|
106
|
-
Since OINO is just generating SQL, WHERE-conditions can be defined with [`
|
|
135
|
+
Since OINO is just generating SQL, WHERE-conditions can be defined with [`OINOQueryFilter`](https://pragmatta.github.io/oino-ts/classes/common_src.OINOQueryFilter.html), order with [`OINOQueryOrder`](https://pragmatta.github.io/oino-ts/classes/common_src.OINOQueryOrder.html), limits/paging with [`OINOQueryLimit`](https://pragmatta.github.io/oino-ts/classes/common_src.OINOQueryLimit.html) and aggregation with [`OINOQueryAggregate`](https://pragmatta.github.io/oino-ts/classes/common_src.OINOQueryAggregate.html) that are passed as HTTP request parameters. No more API development where you make unique API endpoints for each filter that fetch all data with original API and filter in backend code. Every API can be filtered when and as needed without unnessecary data tranfer and utilizing SQL indexing when available.
|
|
136
|
+
|
|
137
|
+
Most of the filtering also works with NoSQL and Blob datasources but might less performant depending if the service supports it or if we result in software filtering the results.
|
|
107
138
|
|
|
108
139
|
## Swagger Support
|
|
109
140
|
Swagger is great as long as the definitions are updated and with OINO you can automatically get a Swagger definition including a data model schema.
|
|
@@ -118,28 +149,26 @@ if (url.pathname == "/swagger.json") {
|
|
|
118
149
|
OINO is developped Typescript first but compiles to standard CommonJS and the NPM packages should work on either ESM / CommonJS. Checkout sample apps `readmeApp` (ESM) and `nodeApp` (CommonJS).
|
|
119
150
|
|
|
120
151
|
## HTMX support
|
|
121
|
-
OINO is [htmx.org](https://htmx.org)
|
|
152
|
+
OINO is [htmx.org](https://htmx.org)-friendly, allowing easy translation of [`OINODataRow`](https://pragmatta.github.io/oino-ts/types/db_src.OINODataRow.html) to HTML output using templates (cf. the [htmx sample app](https://github.com/pragmatta/oino-ts/tree/main/samples/htmxApp)).
|
|
122
153
|
|
|
123
154
|
## Hashids
|
|
124
155
|
Autoinc numeric id's are very pragmatic and fit well with OINO (e.g. using a form without primary key fields to insert new rows with database assigned ids). However it's not always sensible to share information about the sequence. Hashids solve this by masking the original values by encrypting the ids using AES-128 and some randomness. Length of the hashid can be chosen from 12-32 characters where longer ids provide more security. However this should not be considereded a cryptographic solution for keeping ids secret but rather making it infeasible to iterate all ids.
|
|
125
156
|
|
|
157
|
+
### Batch updates
|
|
158
|
+
Batch updates slight bend the RESTfull principles but there are separate `doBatchUpdate` endpoints (e.g. [OINODbApi.dobatchupdate](https://pragmatta.github.io/oino-ts/classes/db_src.OINODbApi.html#dobatchupdate)).
|
|
126
159
|
|
|
127
|
-
|
|
128
|
-
OINO
|
|
160
|
+
## Schema Management
|
|
161
|
+
OINO has endpoints for reading, creating and deleting table and column schemas.
|
|
129
162
|
|
|
130
|
-
## Roadmap
|
|
131
|
-
Major features that are considered in future releases ()
|
|
132
163
|
|
|
133
|
-
|
|
134
|
-
|
|
164
|
+
# STATUS
|
|
165
|
+
OINO v1.1 is the first release considered production status. Architecture has now survived introduction NoSQL and Blov datasources and we feel comfortable saying it's stable now. Also we have been using it in [oino.cloud](https://oino.cloud) for a while without issues.
|
|
135
166
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
- What edge cases exist in updating views?
|
|
139
|
-
- Can views be handled transparently to the DBMS or is there some fundamentally platform specific behavior?
|
|
167
|
+
## Roadmap
|
|
168
|
+
Major features that are considered in future releases
|
|
140
169
|
|
|
141
|
-
###
|
|
142
|
-
|
|
170
|
+
### Views
|
|
171
|
+
It would be interesting to combine multiple datasources as OINO-views like multiple NoSQL-tables.
|
|
143
172
|
|
|
144
173
|
### Streaming
|
|
145
174
|
One core idea is to be efficient in not making unnecessary copies of the data and minimizing garbage collection debt. This can be taken further by implementing streaming, allowing large dataset to be written to HTTP response as SQL result rows are received.
|
|
@@ -147,9 +176,6 @@ One core idea is to be efficient in not making unnecessary copies of the data an
|
|
|
147
176
|
### SQL generation callbacks
|
|
148
177
|
It would be useful to allow developer to validate / override SQL generation to cover cases OINO does not support or even workaround issues.
|
|
149
178
|
|
|
150
|
-
### Transactions
|
|
151
|
-
Even though the basic case for OINO is executing SQL operations on individual rows, having an option to use SQL transactions could make sense at least for batch operations.
|
|
152
|
-
|
|
153
179
|
|
|
154
180
|
# HELP
|
|
155
181
|
|
|
@@ -159,8 +185,6 @@ Fixing bugs is a priority and getting good quality bug reports helps. It's recom
|
|
|
159
185
|
## Feedback
|
|
160
186
|
Understanding and prioritizing the use cases for OINO is also important and feedback about how you'd use OINO is interesting. Feel free to raise issues and feature requests in Github, but understand that short term most of the effort goes towards reaching the beta stage.
|
|
161
187
|
|
|
162
|
-
## Typescript / Javascript architecture
|
|
163
|
-
Typescript building with different targets and module-systemts and a ton of configuration is a complex domain and something I have little experience un so help in fixing problems and how thing ought to be done is appreciated.
|
|
164
188
|
|
|
165
189
|
# LINKS
|
|
166
190
|
- [Github repository](https://github.com/pragmatta/oino-ts)
|
|
@@ -171,10 +195,12 @@ Typescript building with different targets and module-systemts and a ton of conf
|
|
|
171
195
|
|
|
172
196
|
## Libraries
|
|
173
197
|
OINO uses the following open source libraries and npm packages and I would like to thank everyone for their contributions:
|
|
174
|
-
- Postgresql [node-postgres package](https://
|
|
175
|
-
- Mariadb / Mysql [mariadb package](https://
|
|
176
|
-
- Sql Server [mssql package](https://
|
|
177
|
-
- Custom base encoding [base-x package](https://
|
|
198
|
+
- Postgresql [node-postgres package](https://github.com/brianc/node-postgres)
|
|
199
|
+
- Mariadb / Mysql [mariadb package](https://github.com/mariadb-corporation/mariadb-connector-nodejs)
|
|
200
|
+
- Sql Server [mssql package](https://github.com/tediousjs/node-mssql)
|
|
201
|
+
- Custom base encoding [base-x package](https://github.com/cryptocoinjs/base-x)
|
|
202
|
+
- AWS JS SDK [aws-sdk](https://github.com/aws/aws-sdk-js-v3)
|
|
203
|
+
- Azure JS SDK [azure](https://github.com/Azure/azure-sdk-for-js)
|
|
178
204
|
|
|
179
205
|
## Bun
|
|
180
206
|
OINO has been developed using the Bun runtime, not because of the speed improvements but for the first class Typescript support and integrated developper experience. Kudos on the bun team for making Typescript work more exiting again.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oino-ts/hashid",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "OINO TS package for hashid's.",
|
|
5
5
|
"author": "Matias Kiviniemi (pragmatta)",
|
|
6
6
|
"license": "MPL-2.0",
|
|
@@ -18,12 +18,12 @@
|
|
|
18
18
|
"types": "./dist/types/index.d.ts",
|
|
19
19
|
"dependencies": {
|
|
20
20
|
"@types/node": "^20.12.7",
|
|
21
|
-
"@oino-ts/common": "1.0
|
|
21
|
+
"@oino-ts/common": "1.1.0",
|
|
22
22
|
"base-x": "^5.0.1"
|
|
23
23
|
},
|
|
24
24
|
"devDependencies": {
|
|
25
25
|
"typescript": "~5.9.0",
|
|
26
|
-
"@oino-ts/types": "1.0
|
|
26
|
+
"@oino-ts/types": "1.1.0"
|
|
27
27
|
},
|
|
28
28
|
"files": [
|
|
29
29
|
"src/*.ts",
|