prostgles-client 4.0.252 → 4.0.254
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 +157 -14
- package/dist/index.js +1 -2
- package/dist/index.no-sync.js +1 -2
- package/dist/react-hooks.d.ts.map +1 -1
- package/dist/react-hooks.js +2 -1
- package/package.json +4 -7
- package/webpack.prod.js +18 -17
- package/dist/index.js.LICENSE.txt +0 -9
- package/dist/index.no-sync.js.LICENSE.txt +0 -9
package/README.md
CHANGED
|
@@ -1,46 +1,189 @@
|
|
|
1
1
|
# prostgles-client
|
|
2
|
-
|
|
2
|
+
|
|
3
|
+
Isomorphic TypeScript client for PostgreSQL
|
|
3
4
|
|
|
4
5
|
[](https://github.com/prostgles/prostgles-client-js/blob/master/LICENSE)
|
|
5
6
|
[](https://www.npmjs.com/package/prostgles-client)
|
|
6
|
-
[](https://david-dm.org/prostgles/prostgles-client-js/status.svg#info=dependencies)
|
|
7
7
|
[](https://snyk.io/test/github/prostgles/prostgles-client-js)
|
|
8
8
|
|
|
9
9
|
|
|
10
|
+
## Features
|
|
10
11
|
|
|
12
|
+
- 🔄 Real-time data synchronization - Subscribe to database changes with WebSocket support
|
|
13
|
+
- 🔒 End-to-end type safety - Auto-generated TypeScript types from your database schema
|
|
14
|
+
- ⚛️ React hooks - First-class React support with useFind, useSubscribe and useSync
|
|
15
|
+
- 🌐 Isomorphic - Works in Node.js and browsers
|
|
16
|
+
- 🚀 Zero boilerplate - Direct database access without writing SQL
|
|
17
|
+
- 🔗 Relational queries - Join tables with intuitive syntax
|
|
11
18
|
|
|
12
19
|
## Installation
|
|
13
20
|
|
|
14
|
-
|
|
21
|
+
npm/yarn
|
|
22
|
+
|
|
15
23
|
```bash
|
|
16
24
|
$ npm install prostgles-client socket.io-client
|
|
17
25
|
```
|
|
18
26
|
|
|
19
27
|
CDN
|
|
28
|
+
|
|
20
29
|
```html
|
|
21
30
|
<head>
|
|
22
|
-
|
|
23
|
-
|
|
31
|
+
<script
|
|
32
|
+
src="https://unpkg.com/socket.io-client@3.0.3/dist/socket.io.min.js"
|
|
33
|
+
type="text/javascript"
|
|
34
|
+
></script>
|
|
35
|
+
<script
|
|
36
|
+
src="https://unpkg.com/prostgles-client@latest/dist/index.js"
|
|
37
|
+
type="text/javascript"
|
|
38
|
+
></script>
|
|
24
39
|
</head>
|
|
25
40
|
```
|
|
26
41
|
|
|
27
|
-
##
|
|
28
|
-
|
|
42
|
+
## Quick Start
|
|
43
|
+
|
|
44
|
+
### React hooks
|
|
45
|
+
|
|
46
|
+
Subscribe to data changes with automatic re-renders:
|
|
47
|
+
|
|
48
|
+
```tsx
|
|
49
|
+
import { useProstglesClient } from "prostgles-client/dist/prostgles";
|
|
50
|
+
import type { DBGeneratedSchema } from "@common/DBGeneratedSchema";
|
|
51
|
+
|
|
52
|
+
const App = () => {
|
|
53
|
+
const client = useProstglesClient<DBGeneratedSchema>({ socketOptions: { path: "/ws-api" } });
|
|
54
|
+
|
|
55
|
+
if(client.isLoading) return "Loading...";
|
|
56
|
+
if(client.hasError) return <>Error: {client.error}</>;
|
|
57
|
+
|
|
58
|
+
return <UserPosts dbo={client.dbo} />
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
const UserPosts = ({ dbo }: { dbo: }) => {
|
|
62
|
+
|
|
63
|
+
const { data: user, isLoading } = dbo.users.useSubscribeOne(
|
|
64
|
+
{ id: 1 },
|
|
65
|
+
{
|
|
66
|
+
select: {
|
|
67
|
+
id: 1,
|
|
68
|
+
first_name: 1,
|
|
69
|
+
email: 1,
|
|
70
|
+
latest_posts: {
|
|
71
|
+
$leftJoin: ["posts"],
|
|
72
|
+
orderBy: { created: -1 }
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
);
|
|
77
|
+
|
|
78
|
+
if(isLoading) return "Loading ..."
|
|
79
|
+
|
|
80
|
+
return (
|
|
81
|
+
<div>
|
|
82
|
+
<h1>{user.first_name}</h1>
|
|
83
|
+
<p>{user.email}</p>
|
|
84
|
+
<h2>Latest Posts</h2>
|
|
85
|
+
<ul>
|
|
86
|
+
{user.latest_posts.map(post => (
|
|
87
|
+
<li key={post.id}>{post.title}</li>
|
|
88
|
+
))}
|
|
89
|
+
</ul>
|
|
90
|
+
</div>
|
|
91
|
+
);
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Vanilla JavaScript
|
|
96
|
+
|
|
29
97
|
```js
|
|
30
98
|
prostgles({
|
|
31
|
-
socket: io(),
|
|
99
|
+
socket: io(),
|
|
32
100
|
onReady: async (db) => {
|
|
33
|
-
const latest_posts = await db.posts.find({
|
|
34
|
-
|
|
101
|
+
const latest_posts = await db.posts.find({}, { orderBy: { created: -1 } });
|
|
102
|
+
|
|
103
|
+
// Insert data
|
|
104
|
+
await dbo.posts.insert({
|
|
105
|
+
title: "Hello World",
|
|
106
|
+
content: "My first post",
|
|
107
|
+
published: true,
|
|
108
|
+
});
|
|
109
|
+
},
|
|
35
110
|
});
|
|
36
111
|
```
|
|
37
|
-
|
|
112
|
+
|
|
113
|
+
## Type Safety
|
|
114
|
+
|
|
115
|
+
Paired with [prostgles-server](https://www.npmjs.com/package/prostgles-server), types are automatically generated from your database schema:
|
|
116
|
+
|
|
117
|
+
Learn more in the [Prostgles documentation](https://prostgles.com/api-docs).
|
|
118
|
+
|
|
119
|
+
## API Overview
|
|
120
|
+
|
|
121
|
+
### Query Methods
|
|
122
|
+
|
|
123
|
+
- find() - Fetch multiple records
|
|
124
|
+
- findOne() - Fetch a single record
|
|
125
|
+
- useFind() - React hook for find()
|
|
126
|
+
- useFindOne() - React hook for findOne()
|
|
127
|
+
- count() - Count records
|
|
128
|
+
- useCount() - React hook for count()
|
|
129
|
+
- insert() - Insert new records
|
|
130
|
+
- update() - Update existing records
|
|
131
|
+
- delete() - Delete records
|
|
132
|
+
- upsert() - Insert or update records
|
|
133
|
+
|
|
134
|
+
### Real-time Methods
|
|
135
|
+
|
|
136
|
+
- subscribe() - Subscribe to multiple records
|
|
137
|
+
- subscribeOne() - Subscribe to a single record
|
|
138
|
+
- sync() - Two-way sync for multiple records (local changes pushed to server)
|
|
139
|
+
- syncOne() - Two-way sync for a single record (local changes pushed to server)
|
|
140
|
+
- useSubscribe() - React hook for subscribe()
|
|
141
|
+
- useSubscribeOne() - React hook for subscribeOne()
|
|
142
|
+
- useSync() - React hook for sync()
|
|
143
|
+
- useSyncOne() - React hook for syncOne()
|
|
144
|
+
|
|
145
|
+
### Sync vs Subscribe
|
|
146
|
+
|
|
147
|
+
The key difference between **sync** and **subscribe** methods:
|
|
148
|
+
|
|
149
|
+
- **Subscribe** (subscribe, subscribeOne) - One-way data flow from server to client. Receives updates when data changes on the server.
|
|
150
|
+
- **Sync** (sync, syncOne) - Two-way data flow. Allows local optimistic updates that are automatically synced back to the server, while also receiving server updates.
|
|
151
|
+
|
|
38
152
|
```tsx
|
|
39
|
-
|
|
40
|
-
const
|
|
153
|
+
// Sync: locally modified data is propagated instantly to the client
|
|
154
|
+
const { data: draftPost, isLoading } = dbo.posts.useSyncOne(
|
|
155
|
+
{ published: false },
|
|
156
|
+
{ handlesOnData: true },
|
|
157
|
+
);
|
|
158
|
+
if (isLoading) return "Loading...";
|
|
159
|
+
if (!draftPost) {
|
|
160
|
+
return <button onClick={() => dbo.posts.insert({ published: false })}>Create new post</button>;
|
|
161
|
+
}
|
|
162
|
+
return (
|
|
163
|
+
<form>
|
|
164
|
+
<input
|
|
165
|
+
type="text"
|
|
166
|
+
placeholder="Title"
|
|
167
|
+
value={draftPost.title}
|
|
168
|
+
onChange={(e) => draftPost.$update({ title: e.target.value })}
|
|
169
|
+
/>
|
|
170
|
+
<input
|
|
171
|
+
type="text"
|
|
172
|
+
placeholder="Content"
|
|
173
|
+
value={draftPost.content}
|
|
174
|
+
onChange={(e) => draftPost.$update({ content: e.target.value })}
|
|
175
|
+
/>
|
|
176
|
+
<button onClick={() => draftPost.$update({ published: true })}>Publish</button>
|
|
177
|
+
</form>
|
|
178
|
+
);
|
|
41
179
|
```
|
|
180
|
+
|
|
181
|
+
## Documentation
|
|
182
|
+
|
|
183
|
+
[Full API Documentation](https://prostgles.com/api-docs)
|
|
42
184
|
[Examples](https://github.com/prostgles/prostgles-server-js/tree/master/examples)
|
|
185
|
+
[Server Setup Guide](https://www.npmjs.com/package/prostgles-server)
|
|
43
186
|
|
|
44
187
|
## License
|
|
45
188
|
|
|
46
|
-
|
|
189
|
+
[MIT](LICENSE)
|