prostgles-client 4.0.251 → 4.0.253

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 (4) hide show
  1. package/README.md +157 -14
  2. package/dist/index.js +1 -1
  3. package/dist/index.no-sync.js +1 -1
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -1,46 +1,189 @@
1
1
  # prostgles-client
2
- Isomorphic TypeScript client for PostgreSQL
2
+
3
+ Isomorphic TypeScript client for PostgreSQL
3
4
 
4
5
  [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/prostgles/prostgles-client-js/blob/master/LICENSE)
5
6
  [![npm version](https://img.shields.io/npm/v/prostgles-client.svg?style=flat)](https://www.npmjs.com/package/prostgles-client)
6
- [![Dependency Status](https://david-dm.org/prostgles/prostgles-client-js/status.svg)](https://david-dm.org/prostgles/prostgles-client-js/status.svg#info=dependencies)
7
7
  [![Known Vulnerabilities](https://snyk.io/test/github/prostgles/prostgles-client-js/badge.svg)](https://snyk.io/test/github/prostgles/prostgles-client-js)
8
8
  ![Tests](https://github.com/prostgles/prostgles-server-js/actions/workflows/main.yml/badge.svg)
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
- Module
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
- <script src="https://unpkg.com/socket.io-client@3.0.3/dist/socket.io.min.js" type="text/javascript"></script>
23
- <script src="https://unpkg.com/prostgles-client@latest/dist/index.js" type="text/javascript"></script>
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
- ## Usage
28
- ### Vanilla js
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({ }, { orderBy: { created: -1 } });
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
- ### React hooks
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
- const latest_posts = dbo.posts.useFind({ }, { orderBy: { created: -1 } });
40
- const user = dbo.users.useSubscribeOne({ id: 1 });
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
- [MIT](LICENSE)
189
+ [MIT](LICENSE)