@codenotch/codenotch.cli 1.0.56 → 1.0.57

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 (27) hide show
  1. package/dist/commands/generate/app.js +3 -1
  2. package/dist/commands/generate/app.js.map +1 -1
  3. package/dist/commands/generate/dbcontext.js +2 -2
  4. package/dist/commands/generate/dbcontext.js.map +1 -1
  5. package/dist/commands/generate/index.js +1 -1
  6. package/dist/utils/BuildUtils.d.ts +7 -5
  7. package/dist/utils/BuildUtils.js +7 -5
  8. package/dist/utils/BuildUtils.js.map +1 -1
  9. package/dist/utils/DbSchemaUtils.d.ts +21 -4
  10. package/dist/utils/DbSchemaUtils.js +79 -4
  11. package/dist/utils/DbSchemaUtils.js.map +1 -1
  12. package/dist/utils/ProjectGeneratorUtils.d.ts +6 -1
  13. package/dist/utils/ProjectGeneratorUtils.js +34 -8
  14. package/dist/utils/ProjectGeneratorUtils.js.map +1 -1
  15. package/dist/utils/ProjectTemplates.d.ts +6 -4
  16. package/dist/utils/ProjectTemplates.js +10 -8
  17. package/dist/utils/ProjectTemplates.js.map +1 -1
  18. package/dist/utils/ProjectUtils.d.ts +10 -1
  19. package/dist/utils/ProjectUtils.js +19 -5
  20. package/dist/utils/ProjectUtils.js.map +1 -1
  21. package/dist/utils/TemplateUtils.d.ts +15 -1
  22. package/dist/utils/TemplateUtils.js +48 -11
  23. package/dist/utils/TemplateUtils.js.map +1 -1
  24. package/package.json +1 -1
  25. package/resources/docs/apps.md +54 -8
  26. package/resources/docs/project.md +4 -3
  27. package/resources/docs/tables.md +7 -2
package/resources/docs/apps.md CHANGED
@@ -50,10 +50,11 @@ The manifest carries the display and PWA settings:
50
50
  - **react-router 7** for multi-page apps, with `HashRouter`: it keeps the routing client side
51
51
  whatever URL the runtime serves the app from.
52
52
  - **`@codenotch/codenotch.react`** — the bridge to the runtime, through `useCodenotch()`.
53
- - **`@codenotch/process` and `@codenotch/orm` are server-side**: a value import from app code
54
- fails the build with an explicit error (there is nothing to bundle for a browser).
55
- `import type { ... }` is fine — types are erased. Server logic belongs in a process the app
56
- calls.
53
+ - **`@codenotch/process` is server-side**: a value import from app code fails the build with an
54
+ explicit error (there is nothing to bundle for a browser). `import type { ... }` is fine —
55
+ types are erased. Server logic belongs in a process the app calls.
56
+ - **`@codenotch/orm` ships in the browser**: the table declarations are what the generated
57
+ `db-client-context.ts` imports to query them from the apps (see below).
57
58
  - **Importing a process from an app is allowed and safe**: in the app build the process file is
58
59
  replaced by client handles — each exported process becomes `{ __codenotchProcess: true, id }`,
59
60
  so `myProcess.id` works at runtime and `typeof myProcess` still types. Nothing else of that
@@ -69,12 +70,57 @@ What the generated code relies on:
69
70
  | `cn.env` | the environment the runtime gave the app |
70
71
  | `cn.getTheme()` / `cn.setTheme('light' \| 'dark')` | theme; `setTheme` toggles the `dark` class on `<html>` |
71
72
  | `cn.getLanguage()` / `cn.setLanguage(lang)` / `cn.getLanguages()` | languages, from `manifest.json` |
72
- | `cn.startProcess(processId, input)` | call a server-side process — **not implemented yet** in `@codenotch/codenotch.react` 2.0.5 (it throws `Not implemented.`) |
73
+ | `cn.startProcess(process, input)` | start a server-side process and wait for its result: `process` is the handle imported from its file under `processes/`, `input` and `result.output` are typed by its `run`. `cn.startProcessFromId(id, input)` is the untyped variant |
74
+ | `cn.tables.<name>` | the tables of the project, one `ClientTableQueryable` each (`.filter(...)`, `.run()`, `.first()`) — only when the hook is given the client context, see below |
73
75
 
74
76
  For the full surface, read the typings in
75
- `node_modules/@codenotch/codenotch.react/dist/`. Because `startProcess` is not settled, generated
76
- projects wrap it in one typed `apps/api.ts` module carrying a `TODO` comment — keep that pattern
77
- instead of scattering direct calls.
77
+ `node_modules/@codenotch/codenotch.react/dist/`.
78
+
79
+ ### Calling a process
80
+
81
+ Import the process from its file and start it: the app build replaces the process file by client
82
+ handles (`{ id }`), so nothing server-side reaches the browser, and the types still flow from the
83
+ `run` of the process. Generated projects gather every call in one `apps/api.ts` module that
84
+ unwraps the result — keep that pattern instead of scattering direct calls:
85
+
86
+ ```ts
87
+ import { getCodenotch, type Process } from '@codenotch/codenotch.react';
88
+ import * as todos from '../processes/todos';
89
+
90
+ async function call<In, Out>(process: Process<In, Out, any>, input: In): Promise<Out> {
91
+ const result = await getCodenotch().startProcess(process, input);
92
+ if (result.isError) {
93
+ throw new Error(result.errorMessage);
94
+ }
95
+ return result.output;
96
+ }
97
+
98
+ export const createTodo = (listId: string, title: string) => call(todos.createTodo, { listId, title });
99
+ ```
100
+
101
+ `result.isError` is set when the start fails, when the process ends in error or when it times
102
+ out (30 s); `result.processInstanceId` identifies the run. Inside a component, `useCodenotch()`
103
+ gives the same `startProcess`.
104
+
105
+ ### The client context
106
+
107
+ `cn generate dbcontext -f .` (and every compile) writes `db-client-context.ts` at the root of a
108
+ project that has tables **and** at least one app: a `clientDbContext` object holding one
109
+ `ClientTableQueryable` per exported table, under the same collection name as `ctx.tables` in the
110
+ processes (`TodoList` → `todolists`). Hand it to the hook and `cn.tables` is typed:
111
+
112
+ ```tsx
113
+ import { useCodenotch } from '@codenotch/codenotch.react';
114
+ import { clientDbContext } from '../db-client-context';
115
+
116
+ const cn = useCodenotch(clientDbContext);
117
+ const lists = await cn.tables.todolists.run();
118
+ ```
119
+
120
+ Pass the module-level `clientDbContext` itself, never an object built during render, otherwise
121
+ the API the hook returns changes on every render. A project without app has no client context
122
+ (nothing would import it), and a table left out of it is reported by the generation (not
123
+ exported, or two tables mapping to the same collection name).
78
124
 
79
125
  ## Styling
80
126
 
package/resources/docs/project.md CHANGED
@@ -50,6 +50,7 @@ fixed unless the user explicitly asks for a rename.
50
50
  | --- | --- | --- |
51
51
  | `db-schema.xml` | the `defineEntity` declarations | `cn generate dbcontext -f .` |
52
52
  | `db-schema.d.ts` | same — types `ctx.tables` by declaration merging | `cn generate dbcontext -f .` |
53
+ | `db-client-context.ts` | same, when the project has apps — the tables as the apps query them, for `useCodenotch(clientDbContext)` | `cn generate dbcontext -f .` |
53
54
  | `openapi.json` | the processes exposing endpoints | `cn generate openapi -f .` |
54
55
  | `*.i18n.ts` | its sibling `*.i18n.csv` | `cn generate i18n -f <file>.i18n.csv` |
55
56
  | `.codenotch/` | build outputs: compiled project, package zip, React staging | `cn project compile` / `package`, `cn react build` |
@@ -108,6 +109,6 @@ Packaging typechecks the whole project first: type errors fail it.
108
109
 
109
110
  ## The TODO policy
110
111
 
111
- Where the runtime API is not settled yet (the client-side call of a process, the CNQL filter
112
- syntax), the code carries an explicit `TODO` comment instead of a guess. Keep that policy: never
113
- invent an API shape where the existing sources marked one as unsettled.
112
+ Where the runtime API is not settled yet (the CNQL filter syntax), the code carries an explicit
113
+ `TODO` comment instead of a guess. Keep that policy: never invent an API shape where the existing
114
+ sources marked one as unsettled.
package/resources/docs/tables.md CHANGED
@@ -86,12 +86,17 @@ name, **not** pluralized, and typed as document-store handles rather than table
86
86
  cn generate dbcontext -f .
87
87
  ```
88
88
 
89
- writes two files at the project root — both generated, never edit them:
89
+ writes up to three files at the project root — all generated, never edit them:
90
90
 
91
91
  - `db-schema.xml` — the schema the runtime migrates the database from;
92
92
  - `db-schema.d.ts` — augments the `ProjectTables` and `ProjectDocs` interfaces of
93
93
  `@codenotch/process` by declaration merging, so `ctx.tables.<collection>` autocompletes with
94
- the row type of the table.
94
+ the row type of the table;
95
+ - `db-client-context.ts` — only when the project has at least one app: the same tables as the
96
+ React apps query them, a `clientDbContext` object holding one `ClientTableQueryable` of
97
+ `@codenotch/codenotch.react` per **exported** table (`export const TodoList = defineEntity(...)`),
98
+ under the same collection names. Apps hand it to the hook: `useCodenotch(clientDbContext)`, then
99
+ `cn.tables.<collection>` is typed (see `cn docs apps`). Documents are not part of it.
95
100
 
96
101
  Regenerate after every change to a `defineEntity`/`defineDocument` declaration. The project's
97
102
  `tsconfig.json` must keep `db-schema.d.ts` in its `include` for the merging to apply.