astro-loader-pocketbase 0.3.0-rc.3 → 0.4.0-rc.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.
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# astro-loader-pocketbase
|
|
2
2
|
|
|
3
3
|
<!--  -->
|
|
4
|
+
|
|
4
5
|
[](https://www.npmjs.com/package/astro-loader-pocketbase)
|
|
5
6
|
[](https://www.npmjs.com/package/astro-loader-pocketbase)
|
|
6
7
|
[](https://github.com/pawcoding/astro-loader-pocketbase/blob/master/LICENSE)
|
|
@@ -8,21 +9,22 @@
|
|
|
8
9
|
|
|
9
10
|
This package is a simple loader to load data from a PocketBase database into Astro using the [Astro Loader API](https://5-0-0-beta.docs.astro.build/en/reference/loader-reference/) introduced in Astro 5.
|
|
10
11
|
|
|
11
|
-
##
|
|
12
|
+
## Basic usage
|
|
12
13
|
|
|
13
14
|
In your content configuration file, you can use the `pocketbaseLoader` function to use your PocketBase database as a data source.
|
|
14
15
|
|
|
15
16
|
```ts
|
|
16
|
-
import { pocketbaseLoader } from "astro-pocketbase
|
|
17
|
+
import { pocketbaseLoader } from "astro-loader-pocketbase";
|
|
17
18
|
import { defineCollection } from "astro:content";
|
|
18
19
|
|
|
19
20
|
const blog = defineCollection({
|
|
20
21
|
loader: pocketbaseLoader({
|
|
21
22
|
url: "https://<your-pocketbase-url>",
|
|
22
|
-
collectionName: "<collection-in-pocketbase>"
|
|
23
|
-
content: "<field-in-collection>"
|
|
23
|
+
collectionName: "<collection-in-pocketbase>"
|
|
24
24
|
})
|
|
25
25
|
});
|
|
26
|
+
|
|
27
|
+
export const collections = { blog };
|
|
26
28
|
```
|
|
27
29
|
|
|
28
30
|
By default, the loader will only fetch entries that have been modified since the last build.
|
|
@@ -31,43 +33,120 @@ If you want to update your deployed site with new entries, you need to rebuild i
|
|
|
31
33
|
|
|
32
34
|
<sub>When running the dev server, you can trigger a reload by using `s + enter`.</sub>
|
|
33
35
|
|
|
34
|
-
|
|
36
|
+
## Entries
|
|
37
|
+
|
|
38
|
+
After generating the schema (see below), the loader will automatically parse the content of the entries (e.g. transform ISO dates to `Date` objects, coerce numbers, etc.).
|
|
39
|
+
|
|
40
|
+
### HTML content
|
|
41
|
+
|
|
42
|
+
You can also specify a field or an array of fields to use as content.
|
|
43
|
+
This content will then be used when calling the `render` function of [Astros content collections](https://5-0-0-beta.docs.astro.build/en/guides/content-collections/#rendering-body-content).
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
const blog = defineCollection({
|
|
47
|
+
loader: pocketbaseLoader({
|
|
48
|
+
...options,
|
|
49
|
+
content: "<field-in-collection>"
|
|
50
|
+
})
|
|
51
|
+
});
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Since the goal of the `render` function is to render the content as HTML, it's recommended to use a field of type `editor` (rich text) in PocketBase as content.
|
|
55
|
+
|
|
56
|
+
If you specify an array of fields, the loader will wrap the content of these fields in a `<section>` and concatenate them.
|
|
57
|
+
|
|
58
|
+
### Images and files
|
|
59
|
+
|
|
60
|
+
PocketBase can store images and files for each entry in a collection.
|
|
61
|
+
While the API only returns the filenames of these images and files, the loader will out of the box **transform these filenames to the actual URLs** of the files.
|
|
62
|
+
This doesn't mean that the files are downloaded during the build process.
|
|
63
|
+
But you can directly use these URLs in your Astro components to display images or link to the files.
|
|
64
|
+
|
|
65
|
+
## Type generation
|
|
35
66
|
|
|
36
67
|
The loader can automatically generate types for your collection.
|
|
37
68
|
This is useful for type checking and autocompletion in your editor.
|
|
38
69
|
These types can be generated in two ways:
|
|
39
70
|
|
|
40
|
-
|
|
71
|
+
### Remote schema
|
|
41
72
|
|
|
42
73
|
To use the lice remote schema, you need to provide the email and password of an admin of the PocketBase instance.
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
const blog = defineCollection({
|
|
77
|
+
loader: pocketbaseLoader({
|
|
78
|
+
...options,
|
|
79
|
+
adminEmail: "<admin-email>",
|
|
80
|
+
adminPassword: "<admin-password>"
|
|
81
|
+
})
|
|
82
|
+
});
|
|
83
|
+
```
|
|
84
|
+
|
|
43
85
|
Under the hood, the loader will use the [PocketBase API](https://pocketbase.io/docs/api-collections/#view-collection) to fetch the schema of your collection and generate types with Zod based on that schema.
|
|
44
86
|
|
|
45
|
-
|
|
87
|
+
### Local schema
|
|
46
88
|
|
|
47
89
|
If you don't want to provide the admin credentials (e.g. in a public repository), you can also provide the schema manually via a JSON file.
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
const blog = defineCollection({
|
|
93
|
+
loader: pocketbaseLoader({
|
|
94
|
+
...options,
|
|
95
|
+
localSchema: "<path-to-schema-file>"
|
|
96
|
+
})
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
48
100
|
In PocketBase you can export the schema of the whole database to a `pb_schema.json` file.
|
|
49
101
|
If you provide the path to this file, the loader will use this schema to generate the types locally.
|
|
50
102
|
|
|
51
103
|
When admin credentials are provided, the loader will **always use the remote schema** since it's more up-to-date.
|
|
52
104
|
|
|
53
|
-
|
|
105
|
+
### Manual schema
|
|
54
106
|
|
|
55
107
|
If you don't want to use the automatic type generation, you can also [provide your own schema manually](https://5-0-0-beta.docs.astro.build/en/guides/content-collections/#defining-the-collection-schema).
|
|
56
108
|
This manual schema will **always override the automatic type generation**.
|
|
57
109
|
|
|
58
|
-
|
|
110
|
+
## All options
|
|
111
|
+
|
|
112
|
+
| Option | Type | Required | Description |
|
|
113
|
+
| ---------------- | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
114
|
+
| `url` | `string` | x | The URL of your PocketBase instance. |
|
|
115
|
+
| `collectionName` | `string` | x | The name of the collection in your PocketBase instance. |
|
|
116
|
+
| `content` | `string \| Array<string>` | | The field in the collection to use as content. This can also be an array of fields. |
|
|
117
|
+
| `adminEmail` | `string` | | The email of the admin of the PocketBase instance. This is used for automatic type generation and access to private collections. |
|
|
118
|
+
| `adminPassword` | `string` | | The password of the admin of the PocketBase instance. This is used for automatic type generation and access to private collections. |
|
|
119
|
+
| `localSchema` | `string` | | The path to a local schema file. This is used for automatic type generation. |
|
|
120
|
+
| `jsonSchemas` | `Record<string, z.ZodSchema>` | | A record of Zod schemas to use for type generation of `json` fields. |
|
|
121
|
+
| `forceUpdate` | `boolean` | | If set to `true`, the loader will fetch every entry instead of only the ones modified since the last build. |
|
|
122
|
+
|
|
123
|
+
## Special cases
|
|
124
|
+
|
|
125
|
+
### Private collections
|
|
59
126
|
|
|
60
127
|
If you want to access a private collection, you also need to provide the admin credentials.
|
|
61
128
|
Otherwise, you need to make the collection public in the PocketBase dashboard.
|
|
62
129
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
130
|
+
Generally, it's not recommended to use private collections, especially when users should be able to see images or other files stored in the collection.
|
|
131
|
+
|
|
132
|
+
### View collections
|
|
133
|
+
|
|
134
|
+
Out of the box, the loader also supports collections with the type `view`, though with some limitations.
|
|
135
|
+
To enable incremental builds, the loader needs to know when an entry has been modified.
|
|
136
|
+
Normal `base` collections have a `updated` field that is automatically updated when an entry is modified.
|
|
137
|
+
Thus, `view` collections that don't include this field can't be incrementally built but will be fetched every time.
|
|
138
|
+
|
|
139
|
+
You can also alias another field as `updated` (as long as it's a date field) in your view.
|
|
140
|
+
While this is possible, it's not recommended since it can lead to outdated data not being fetched.
|
|
141
|
+
|
|
142
|
+
### JSON fields
|
|
143
|
+
|
|
144
|
+
PocketBase can store arbitrary JSON data in a `json` field.
|
|
145
|
+
While this data is checked to be valid JSON, there's no schema attached or enforced.
|
|
146
|
+
Theoretically, every entry in a collection can have a different structure in such a field.
|
|
147
|
+
This is why by default the loader will treat these fields as `unknown` and will not generate types for them.
|
|
148
|
+
|
|
149
|
+
If you have your own schema for these fields, you can provide them via the `jsonSchemas` option.
|
|
150
|
+
The keys of this record should be the field names of your json fields, while the values are Zod schemas.
|
|
151
|
+
This way, the loader will also generate types for these fields and **validate the data against these schemas**.
|
|
152
|
+
So be sure that the schema is correct, up-to-date and all entries in the collection adhere to it.
|
package/package.json
CHANGED
package/src/cleanup-entries.ts
CHANGED
|
@@ -26,7 +26,7 @@ export async function cleanupEntries(
|
|
|
26
26
|
}
|
|
27
27
|
|
|
28
28
|
// Prepare pagination variables
|
|
29
|
-
let page =
|
|
29
|
+
let page = 0;
|
|
30
30
|
let totalPages = 0;
|
|
31
31
|
const entries = new Set<string>();
|
|
32
32
|
|
|
@@ -34,7 +34,7 @@ export async function cleanupEntries(
|
|
|
34
34
|
do {
|
|
35
35
|
// Fetch ids from the collection
|
|
36
36
|
const collectionRequest = await fetch(
|
|
37
|
-
`${collectionUrl}?page=${page}&perPage=1000&fields=id`,
|
|
37
|
+
`${collectionUrl}?page=${++page}&perPage=1000&fields=id`,
|
|
38
38
|
{
|
|
39
39
|
headers: collectionHeaders
|
|
40
40
|
}
|
package/src/generate-schema.ts
CHANGED
|
@@ -63,7 +63,7 @@ export async function generateSchema(
|
|
|
63
63
|
}
|
|
64
64
|
|
|
65
65
|
// Parse the schema
|
|
66
|
-
const fields = parseSchema(collection);
|
|
66
|
+
const fields = parseSchema(collection, options.jsonSchemas);
|
|
67
67
|
|
|
68
68
|
// Check if the content field is present
|
|
69
69
|
if (typeof options.content === "string" && !fields[options.content]) {
|
package/src/load-entries.ts
CHANGED
|
@@ -40,7 +40,7 @@ export async function loadEntries(
|
|
|
40
40
|
);
|
|
41
41
|
|
|
42
42
|
// Prepare pagination variables
|
|
43
|
-
let page =
|
|
43
|
+
let page = 0;
|
|
44
44
|
let totalPages = 0;
|
|
45
45
|
let entries = 0;
|
|
46
46
|
let hasUpdatedColumn = !!lastModified;
|
|
@@ -50,7 +50,7 @@ export async function loadEntries(
|
|
|
50
50
|
// Fetch entries from the collection
|
|
51
51
|
// If `lastModified` is set, only fetch entries that have been modified since the last fetch
|
|
52
52
|
const collectionRequest = await fetch(
|
|
53
|
-
`${collectionUrl}?page=${page}&perPage=100${
|
|
53
|
+
`${collectionUrl}?page=${++page}&perPage=100${
|
|
54
54
|
lastModified
|
|
55
55
|
? `&sort=-updated,id&filter=(updated>"${lastModified}")`
|
|
56
56
|
: ""
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import type { z } from "astro/zod";
|
|
2
|
+
|
|
1
3
|
/**
|
|
2
4
|
* Options for the PocketBase loader.
|
|
3
5
|
*/
|
|
@@ -36,6 +38,14 @@ export interface PocketBaseLoaderOptions {
|
|
|
36
38
|
* If admin credentials are provided (see `adminEmail` and `adminPassword`), this option will be ignored.
|
|
37
39
|
*/
|
|
38
40
|
localSchema?: string;
|
|
41
|
+
/**
|
|
42
|
+
* Record of zod schemas for all JSON fields in the collection.
|
|
43
|
+
* The key must be the name of a field in the collection.
|
|
44
|
+
* If no schema is provided for a field, the value will be treated as `unknown`.
|
|
45
|
+
*
|
|
46
|
+
* Note that this will only be used for fields of type `json`.
|
|
47
|
+
*/
|
|
48
|
+
jsonSchemas?: Record<string, z.ZodSchema>;
|
|
39
49
|
/**
|
|
40
50
|
* By default, the loader will only fetch entries that have been modified since the last fetch.
|
|
41
51
|
* If you want to fetch all entries, set this to `true`.
|
|
@@ -5,7 +5,8 @@ import type {
|
|
|
5
5
|
} from "../types/pocketbase-schema.type";
|
|
6
6
|
|
|
7
7
|
export function parseSchema(
|
|
8
|
-
collection: PocketBaseCollection
|
|
8
|
+
collection: PocketBaseCollection,
|
|
9
|
+
customSchemas: Record<string, z.ZodType> | undefined
|
|
9
10
|
): Record<string, z.ZodType> {
|
|
10
11
|
// Prepare the schemas fields
|
|
11
12
|
const fields: Record<string, z.ZodType> = {};
|
|
@@ -51,8 +52,13 @@ export function parseSchema(
|
|
|
51
52
|
fieldType = parseSingleOrMultipleValues(field, z.string());
|
|
52
53
|
break;
|
|
53
54
|
case "json":
|
|
54
|
-
|
|
55
|
-
|
|
55
|
+
if (customSchemas && customSchemas[field.name]) {
|
|
56
|
+
// Use the user defined custom schema for the field
|
|
57
|
+
fieldType = customSchemas[field.name];
|
|
58
|
+
} else {
|
|
59
|
+
// Parse the field as unknown JSON
|
|
60
|
+
fieldType = z.unknown();
|
|
61
|
+
}
|
|
56
62
|
break;
|
|
57
63
|
default:
|
|
58
64
|
// Default to a string
|