Skip to content

Commit 7196e19

Browse files
kafkaskafkas
authored
docs: port docs (#216)
* Port docs * Change wording
1 parent c19cade commit 7196e19

39 files changed

Lines changed: 2040 additions & 4 deletions

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
<div align="center">
2-
<img src="images/logo.png" width="240px" alt="header" />
2+
<img src="docs/images/icon.png" width="240px" alt="header" />
33
</div>
44

55
<h1 align="center">
66
typesync
77
</h1>
88

99
<p align="center">
10-
Autogenerate Firestore model types for all platforms
10+
Schema-first Firestore tooling for types, validation, and visualization
1111
</p>
1212

1313
<p align="center">
@@ -30,7 +30,7 @@ Typesync keeps your database and application code consistent and up-to-date at a
3030
[**View the full documentation (docs) ▸**](https://docs.typesync.org)
3131

3232
<div align="center">
33-
<img src="images/architecture-v3.png" width="600px" alt="header" />
33+
<img src="docs/images/architecture-v3.png" width="600px" alt="header" />
3434
</div>
3535

3636
# Documentation

‎docs/cli/generate-graph.mdx‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: "generate-graph"
3+
icon: "rectangle-terminal"
4+
---
5+
6+
import DefinitionOption from "/snippets/cli-option-definition.mdx";
7+
import OutFileOption from "/snippets/cli-option-out-file.mdx";
8+
import IndentationOption from "/snippets/cli-option-indentation.mdx";
9+
import DebugOption from "/snippets/cli-option-debug.mdx";
10+
import ExampleDefinitionGraph from "/snippets/example-definition-graph.mdx";
11+
import ExampleGenerationGraphBefore from "/snippets/example-generation-graph-before.mdx";
12+
import ExampleGenerationGraph from "/snippets/example-generation-graph.mdx";
13+
14+
Generates a [Mermaid](https://mermaid.js.org) graph for the specified schema and injects it into the specified Markdown file. The generated graph is the visual representation of the database architecture inferred from your schema. You can specify where the graph is inserted within the file using the `--startMarker` and `--endMarker` options. For a detailed guide, see the full [example](#example) below.
15+
16+
## Usage
17+
18+
```bash
19+
typesync generate-graph --definition <filePathOrPattern> --outFile <filePath> --startMarker <startMarker> --endMarker <endMarker> --orientation <indentation> --debug <debug>
20+
```
21+
22+
## Options
23+
24+
<DefinitionOption />
25+
<OutFileOption />
26+
27+
<ParamField type="string" path="startMarker" default="typesync-start">
28+
A marker that indicates the line after which the generated code should be
29+
inserted. Make sure to use a string that is unique within the file. The line
30+
containing the marker must be commented i.e. the marker needs to appear after
31+
the `<!--` (see [example](#example)).
32+
33+
</ParamField>
34+
35+
<ParamField type="string" path="endMarker" default="typesync-end">
36+
A marker that indicates the line before which the generated code should be
37+
inserted. Make sure to use a string that is unique within the file. The line
38+
containing the marker must be commented i.e. the marker needs to appear after
39+
the `<!--` (see [example](#example)).
40+
</ParamField>
41+
42+
<ParamField
43+
type='"vertical" | "horizontal"'
44+
path="orientation"
45+
default="horizontal"
46+
>
47+
The orientation of the generated Mermaid graph. Can be either `"vertical"` or
48+
`"horizontal"` which correspond to the `"TB"` and `"LR"` Mermaid options,
49+
respectively.
50+
</ParamField>
51+
52+
<DebugOption />
53+
54+
## Example
55+
56+
Suppose you have a schema definition file named `models.yml` and a Markdown file named `graph.md`.
57+
58+
<CodeGroup>
59+
<ExampleDefinitionGraph />
60+
<ExampleGenerationGraphBefore />
61+
</CodeGroup>
62+
63+
To generate a Mermaid graph for the defined models and inject them between the `typesync-start` and `typesync-end` markers in the `graph.md` file, you can run the following command:
64+
65+
```bash
66+
typesync generate-graph --definition definition.yml --outFile graph.md --startMarker typesync-start --endMarker typesync-end
67+
```
68+
69+
Once you run the command, Typesync inserts the Mermaid graph definition into the specified section.
70+
71+
<ExampleGenerationGraph />
72+
73+
The graph generated for the above schema looks as follows:
74+
75+
```mermaid
76+
graph LR
77+
node1["authors"] --> node2["{authorId}"]
78+
node3["books"] --> node4["{bookId}"]
79+
node4["{bookId}"] --> node5["chapters"]
80+
node5["chapters"] --> node6["{chapterId}"]
81+
node4["{bookId}"] --> node7["reviews"]
82+
node7["reviews"] --> node8["{reviewId}"]
83+
node4["{bookId}"] --> node9["translations"]
84+
node9["translations"] --> node10["{translationId}"]
85+
```

‎docs/cli/generate-py.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: "generate-py"
3+
icon: "rectangle-terminal"
4+
---
5+
6+
import DefinitionOption from "/snippets/cli-option-definition.mdx";
7+
import OutFileOption from "/snippets/cli-option-out-file.mdx";
8+
import TargetOption from "/snippets/cli-option-target.mdx";
9+
import IndentationOption from "/snippets/cli-option-indentation.mdx";
10+
import DebugOption from "/snippets/cli-option-debug.mdx";
11+
12+
Generates Python/Pydantic type definitions for the specified schema and writes them to the specified file. Typesync first “flattens” your schema, creating new aliases for inline types defined within. It then generates the classes, enums, aliases, etc. including serializers and deserializers.
13+
14+
## Usage
15+
16+
```bash
17+
typesync generate-py --definition <filePathOrPattern> --target <targetEnvironment> --outFile <filePath> --indentation <indentation> --customPydanticBase <classImportPath> --debug <debug>
18+
```
19+
20+
## Options
21+
22+
<DefinitionOption />
23+
<TargetOption />
24+
<OutFileOption />
25+
26+
<ParamField type="string" path="customPydanticBase">
27+
The base class from which all the generated Python models will extend. The base class must extend `pydantic.BaseModel` and the option must be provided in the format `x.y.ModelName`. If this option is not provided, the generated models will extend from `pydantic.BaseModel`.
28+
29+
Example values:
30+
31+
- `custom.MyModel`
32+
- `a.b.c.MyCustomModel`
33+
34+
</ParamField>
35+
36+
<ParamField type="string" path="undefinedSentinelName" default="UNDEFINED">
37+
The name of the sentinel value used to indicate that a field should be missing
38+
from a given object. This is generated as a variable alongside your model
39+
definitions.
40+
</ParamField>
41+
42+
<IndentationOption />
43+
<DebugOption />
44+
45+
## Targets
46+
47+
- `firebase-admin@6`: For Python projects that rely on the [Firebase Admin Python SDK (v6)](https://github.com/firebase/firebase-admin-python).

‎docs/cli/generate-rules.mdx‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: "generate-rules"
3+
icon: "rectangle-terminal"
4+
---
5+
6+
import DefinitionOption from "/snippets/cli-option-definition.mdx";
7+
import OutFileOption from "/snippets/cli-option-out-file.mdx";
8+
import IndentationOption from "/snippets/cli-option-indentation.mdx";
9+
import DebugOption from "/snippets/cli-option-debug.mdx";
10+
import ExampleDefinition from "/snippets/example-definition.mdx";
11+
import ExampleGenerationRulesBefore from "/snippets/example-generation-rules-before.mdx";
12+
import ExampleGenerationRules from "/snippets/example-generation-rules.mdx";
13+
14+
Generates validator functions for Firestore Security Rules (version 2) and injects them into the specified file. These validators ensure that request data adheres to defined model interfaces and detect any modifications to read-only fields during write operations.
15+
16+
Since Security Rules are centralized in a single file (typically `firestore.rules`), and developers often implement custom rules alongside type validations, Typesync inserts only the necessary validator functions, without overriding your custom rules. You can specify where these validators are added within the file using the `--startMarker` and `--endMarker` options. For a detailed guide, see the full [example](#example) below.
17+
18+
<Info>
19+
Note that these validators must adhere to the intrinsic limitations of
20+
Security Rules. For example, while it's feasible to verify if `x` is a list
21+
with the `x is list` predicate, determining whether it's a list of strings is
22+
not possible since loop constructs are not available in Security Rules.
23+
Typesync will provide the most stringent validation possible within these
24+
constraints.
25+
</Info>
26+
27+
## Usage
28+
29+
```bash
30+
typesync generate-rules --definition <filePathOrPattern> --outFile <filePath> --startMarker <startMarker> --endMarker <endMarker> --typeValidatorNamePattern <typeValidatorNamePattern> --typeValidatorParamName <typeValidatorParamName> --indentation <indentation> --debug <debug>
31+
```
32+
33+
## Options
34+
35+
<DefinitionOption />
36+
<OutFileOption />
37+
38+
<ParamField type="string" path="startMarker" default="typesync-start">
39+
A marker that indicates the line after which the generated code should be
40+
inserted. Make sure to use a string that is unique within the file. The line
41+
containing the marker must be commented i.e. the marker needs to appear after
42+
the `//` (see [example](#example)).
43+
44+
</ParamField>
45+
46+
<ParamField type="string" path="endMarker" default="typesync-end">
47+
A marker that indicates the line before which the generated code should be
48+
inserted. Make sure to use a string that is unique within the file. The line
49+
containing the marker must be commented i.e. the marker needs to appear after
50+
the `//` (see [example](#example)).
51+
</ParamField>
52+
53+
<ParamField
54+
type="string"
55+
path="typeValidatorNamePattern"
56+
default="isValid{modelName}"
57+
>
58+
The pattern that specifies how the generated type validators are named. The pattern must be a string that contains the `"{modelName}"` substring (this is a literal value).
59+
60+
Example values:
61+
62+
- `"isValid{modelName}"` -> produces validators like `isValidUser`, `isValidProject`, `isValidAccount` etc.
63+
- `"is{modelName}"` -> produces validators like `isUser`, `isProject`, `isAccount` etc.
64+
65+
</ParamField>
66+
67+
<ParamField type="string" path="typeValidatorParamName" default="data">
68+
The name of the parameter taken by each type validator.
69+
</ParamField>
70+
71+
{/* <ParamField
72+
type="string"
73+
path="readonlyFieldValidatorNamePattern"
74+
default="isReadonlyFieldAffectedFor{modelName}"
75+
>
76+
The pattern that specifies how the generated readonly field validators are named. The pattern must be a string that contains the `"{modelName}"` substring (this is a literal value).
77+
78+
Example values:
79+
80+
- `"isReadonlyFieldAffectedFor{modelName}"` -> produces validators like `isReadonlyFieldAffectedForUser`, `isReadonlyFieldAffectedForProject`, `isReadonlyFieldAffectedForAccount` etc.
81+
- `"affectsReadonlyFieldFor{modelName}"` -> produces validators like `affectsReadonlyFieldForUser`, `affectsReadonlyFieldForProject`, `affectsReadonlyFieldForAccount` etc.
82+
83+
</ParamField> */}
84+
85+
{/* <ParamField
86+
type="string"
87+
path="readonlyFieldValidatorPrevDataParamName"
88+
default="prevData"
89+
>
90+
The name of the first parameter taken by each readonly field validator
91+
representing previous data. This parameter used when computing the diff
92+
between next data and previous data to determine whether a readonly field has
93+
been affected by a write.
94+
</ParamField> */}
95+
96+
{/* <ParamField
97+
type="string"
98+
path="readonlyFieldValidatorNextDataParamName"
99+
default="nextData"
100+
>
101+
The name of the second parameter taken by each readonly field validator
102+
representing next data. This parameter used when computing the diff between
103+
next data and previous data to determine whether a readonly field has been
104+
affected by a write.
105+
</ParamField> */}
106+
107+
<IndentationOption />
108+
<DebugOption />
109+
110+
## Example
111+
112+
Suppose you have a schema definition file named `models.yml` and a Security Rules file named `firestore.rules`.
113+
114+
<CodeGroup>
115+
<ExampleDefinition />
116+
<ExampleGenerationRulesBefore />
117+
</CodeGroup>
118+
119+
120+
{/* TODO: Update */}
121+
122+
To generate validators for the defined models and inject them between the `typesync-start` and `typesync-end` markers in the `firestore.rules` file, you can run the following command:
123+
124+
```bash
125+
typesync generate-rules --definition definition.yml --outFile firestore.rules --startMarker typesync-start --endMarker typesync-end
126+
```
127+
128+
Typesync will insert the `isValidUserRole()` and `isValidUser()` validators into the file. You can then use these validators as needed in your custom rules.
129+
130+
<ExampleGenerationRules />

‎docs/cli/generate-swift.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "generate-swift"
3+
icon: "rectangle-terminal"
4+
---
5+
6+
import DefinitionOption from "/snippets/cli-option-definition.mdx";
7+
import OutFileOption from "/snippets/cli-option-out-file.mdx";
8+
import TargetOption from "/snippets/cli-option-target.mdx";
9+
import IndentationOption from "/snippets/cli-option-indentation.mdx";
10+
import DebugOption from "/snippets/cli-option-debug.mdx";
11+
12+
Generates Swift type definitions for the specified schema and writes them to the specified file. Typesync first "flattens" your schema, creating new aliases for inline types defined within. It then generates the primary and auxiliary structs, enums, aliases, etc. including encoders and decoders.
13+
14+
## Usage
15+
16+
```bash
17+
typesync generate-swift --definition <filePathOrPattern> --target <targetEnvironment> --outFile <filePath> --indentation <indentation> --debug <debug>
18+
```
19+
20+
## Options
21+
22+
<DefinitionOption />
23+
<TargetOption />
24+
<OutFileOption />
25+
<IndentationOption />
26+
<DebugOption />
27+
28+
## Targets
29+
30+
- `firebase@10`: For Swift projects that rely on the [Firebase Apple SDK (v10)](https://github.com/firebase/firebase-ios-sdk).

‎docs/cli/generate-ts.mdx‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: "generate-ts"
3+
icon: "rectangle-terminal"
4+
---
5+
6+
import DefinitionOption from "/snippets/cli-option-definition.mdx";
7+
import OutFileOption from "/snippets/cli-option-out-file.mdx";
8+
import TargetOption from "/snippets/cli-option-target.mdx";
9+
import IndentationOption from "/snippets/cli-option-indentation.mdx";
10+
import DebugOption from "/snippets/cli-option-debug.mdx";
11+
12+
Generates TypeScript type definitions for the specified schema and writes them to the specified file.
13+
14+
## Usage
15+
16+
```bash
17+
typesync generate-ts --definition <filePathOrPattern> --target <targetEnvironment> --outFile <filePath> --indentation <indentation> --debug <debug>
18+
```
19+
20+
## Options
21+
22+
<DefinitionOption />
23+
<TargetOption />
24+
<OutFileOption />
25+
<ParamField
26+
type='"interface" | "type-alias"'
27+
path="objectTypeFormat"
28+
default="interface"
29+
>
30+
31+
Controls how objects are defined in the TypeScript output. Object types can be represented either by interfaces or type aliases.
32+
33+
</ParamField>
34+
<IndentationOption />
35+
<DebugOption />
36+
37+
## Targets
38+
39+
- `firebase-admin@13`: For backend projects that use [Firebase Admin Node.js SDK (v13)](https://www.npmjs.com/package/firebase-admin).
40+
- `firebase-admin@12`: For backend projects that use [Firebase Admin Node.js SDK (v12)](https://www.npmjs.com/package/firebase-admin).
41+
- `firebase-admin@11`: For backend projects that use [Firebase Admin Node.js SDK (v11)](https://www.npmjs.com/package/firebase-admin).
42+
- `firebase-admin@10`: For backend projects that use [Firebase Admin Node.js SDK (v10)](https://www.npmjs.com/package/firebase-admin).
43+
- `firebase@11`: For frontend projects that use [Firebase Javascript SDK (v11)](https://www.npmjs.com/package/firebase).
44+
- `firebase@10`: For frontend projects that use [Firebase Javascript SDK (v10)](https://www.npmjs.com/package/firebase).
45+
- `firebase@9`: For frontend projects that use [Firebase Javascript SDK (v9)](https://www.npmjs.com/package/firebase).
46+
- `react-native-firebase@21`: For React Native projects that use [React Native Firebase (v21)](https://www.npmjs.com/package/@react-native-firebase/firestore).
47+
- `react-native-firebase@20`: For React Native projects that use [React Native Firebase (v20)](https://www.npmjs.com/package/@react-native-firebase/firestore).
48+
- `react-native-firebase@19`: For React Native projects that use [React Native Firebase (v19)](https://www.npmjs.com/package/@react-native-firebase/firestore).

‎docs/cli/validate.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: "validate"
3+
icon: "rectangle-terminal"
4+
---
5+
6+
import DefinitionOption from "/snippets/cli-option-definition.mdx";
7+
import DebugOption from "/snippets/cli-option-debug.mdx";
8+
9+
10+
Checks if the specified schema definition is syntactically valid.
11+
12+
## Usage
13+
14+
```bash
15+
typesync validate --definition <filePathOrPattern> --debug <debug>
16+
```
17+
18+
## Options
19+
20+
<DefinitionOption />
21+
<DebugOption />

0 commit comments

Comments
 (0)