@astrale-os/sdk 0.6.0-beta.6 → 0.6.0-beta.60
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 +220 -66
- package/dist/application/action/action.d.ts +6 -0
- package/dist/application/action/authoring.d.ts +3 -1
- package/dist/application/action/authoring.js +1 -0
- package/dist/application/action/context.d.ts +95 -34
- package/dist/application/action/define.d.ts +3 -3
- package/dist/application/action/index.d.ts +3 -1
- package/dist/application/action/index.js +1 -0
- package/dist/application/define.d.ts +8 -6
- package/dist/application/define.js +28 -14
- package/dist/application/dependency/index.d.ts +1 -1
- package/dist/application/dependency/invoker.d.ts +21 -10
- package/dist/application/domain.d.ts +30 -0
- package/dist/application/error/error.d.ts +16 -1
- package/dist/application/error/error.js +39 -5
- package/dist/application/error/index.d.ts +1 -1
- package/dist/application/error/index.js +1 -1
- package/dist/application/file/binary.d.ts +11 -0
- package/dist/application/file/binary.js +45 -0
- package/dist/application/file/file.d.ts +77 -0
- package/dist/application/file/file.js +111 -0
- package/dist/application/file/index.d.ts +4 -0
- package/dist/application/file/index.js +2 -0
- package/dist/application/file/input.d.ts +13 -0
- package/dist/application/file/input.js +57 -0
- package/dist/application/index.d.ts +6 -5
- package/dist/application/index.js +1 -1
- package/dist/application/integration/define.d.ts +8 -1
- package/dist/application/integration/index.d.ts +2 -2
- package/dist/application/integration/integration.d.ts +13 -1
- package/dist/application/integration/operation.d.ts +16 -3
- package/dist/application/mutation/authoring/builder.d.ts +81 -33
- package/dist/application/mutation/authoring/builder.js +100 -30
- package/dist/application/mutation/authoring/guard.d.ts +37 -0
- package/dist/application/mutation/authoring/guard.js +150 -0
- package/dist/application/mutation/authoring/index.d.ts +5 -2
- package/dist/application/mutation/authoring/index.js +2 -1
- package/dist/application/mutation/authoring/names.d.ts +19 -0
- package/dist/application/mutation/authoring/names.js +83 -0
- package/dist/application/mutation/authoring/properties.d.ts +17 -4
- package/dist/application/mutation/authoring/properties.js +38 -2
- package/dist/application/mutation/authoring/transition.d.ts +3 -2
- package/dist/application/mutation/authoring/transition.js +4 -1
- package/dist/application/mutation/define.d.ts +24 -10
- package/dist/application/mutation/define.js +49 -53
- package/dist/application/mutation/execution/execute.d.ts +2 -2
- package/dist/application/mutation/execution/execute.js +78 -7
- package/dist/application/mutation/execution/executor.d.ts +4 -1
- package/dist/application/mutation/execution/executor.js +6 -1
- package/dist/application/mutation/failure.d.ts +17 -1
- package/dist/application/mutation/failure.js +40 -19
- package/dist/application/mutation/index.d.ts +9 -5
- package/dist/application/mutation/index.js +5 -2
- package/dist/application/mutation/legacy/v6/builder.d.ts +84 -0
- package/dist/application/mutation/legacy/v6/define.d.ts +18 -0
- package/dist/application/mutation/legacy/v6/define.js +56 -0
- package/dist/application/mutation/legacy/v6/mutation.d.ts +28 -0
- package/dist/application/mutation/{authoring → legacy/v6}/precondition.d.ts +4 -0
- package/dist/application/mutation/mutation.d.ts +47 -19
- package/dist/application/query/answer/answer.d.ts +117 -0
- package/dist/application/query/answer/conformance.d.ts +4 -0
- package/dist/application/query/answer/conformance.js +27 -0
- package/dist/application/query/answer/facts.d.ts +17 -0
- package/dist/application/query/answer/facts.js +57 -0
- package/dist/application/query/composite/builder.d.ts +1 -1
- package/dist/application/query/composite/builder.js +2 -2
- package/dist/application/query/composite/plan.d.ts +1 -5
- package/dist/application/query/composite/plan.js +1 -3
- package/dist/application/query/composite/query.d.ts +1 -2
- package/dist/application/query/define.d.ts +3 -34
- package/dist/application/query/define.js +5 -131
- package/dist/application/query/defined/define.d.ts +45 -0
- package/dist/application/query/defined/define.js +96 -0
- package/dist/application/query/defined/query.d.ts +139 -0
- package/dist/application/query/definition.d.ts +12 -0
- package/dist/application/query/definition.js +47 -0
- package/dist/application/query/execution/bounds.d.ts +22 -0
- package/dist/application/query/execution/bounds.js +88 -0
- package/dist/application/query/execution/client.d.ts +21 -0
- package/dist/application/query/execution/crossings.d.ts +30 -0
- package/dist/application/query/execution/crossings.js +232 -0
- package/dist/application/query/execution/error.d.ts +71 -0
- package/dist/application/query/execution/error.js +50 -0
- package/dist/application/query/execution/execute.d.ts +4 -10
- package/dist/application/query/execution/execute.js +3 -45
- package/dist/application/query/execution/executor.d.ts +2 -2
- package/dist/application/query/execution/legacy/declared-classes.d.ts +10 -0
- package/dist/application/query/execution/legacy/declared-classes.js +9 -0
- package/dist/application/query/execution/refusal.d.ts +37 -0
- package/dist/application/query/execution/refusal.js +80 -0
- package/dist/application/query/execution/rows.d.ts +42 -0
- package/dist/application/query/execution/rows.js +326 -0
- package/dist/application/query/execution/run.d.ts +85 -0
- package/dist/application/query/execution/run.js +372 -0
- package/dist/application/query/execution/split.d.ts +24 -0
- package/dist/application/query/execution/split.js +190 -0
- package/dist/application/query/failure.d.ts +8 -0
- package/dist/application/query/failure.js +8 -0
- package/dist/application/query/handles/build.d.ts +10 -0
- package/dist/application/query/handles/build.js +53 -0
- package/dist/application/query/handles/conditions.d.ts +94 -0
- package/dist/application/query/handles/domain.d.ts +157 -0
- package/dist/application/query/handles/handles.d.ts +285 -0
- package/dist/application/query/handles/handles.js +1 -0
- package/dist/application/query/handles/model.d.ts +106 -0
- package/dist/application/query/handles/model.js +261 -0
- package/dist/application/query/handles/plan.d.ts +100 -0
- package/dist/application/query/handles/plan.js +37 -0
- package/dist/application/query/handles/reads.d.ts +106 -0
- package/dist/application/query/handles/reads.js +978 -0
- package/dist/application/query/handles/relations.d.ts +106 -0
- package/dist/application/query/handles/relations.js +1 -0
- package/dist/application/query/handles/rows.d.ts +94 -0
- package/dist/application/query/handles/rows.js +4 -0
- package/dist/application/query/handles/terms.d.ts +103 -0
- package/dist/application/query/handles/terms.js +282 -0
- package/dist/application/query/index.d.ts +14 -8
- package/dist/application/query/index.js +10 -5
- package/dist/application/query/language/index.d.ts +2 -0
- package/dist/application/query/language/index.js +2 -0
- package/dist/application/query/language/query.d.ts +323 -0
- package/dist/application/query/language/query.js +2 -0
- package/dist/application/query/{collection → legacy/v6/collection}/identity.d.ts +2 -2
- package/dist/application/query/{collection → legacy/v6/collection}/metadata.d.ts +1 -1
- package/dist/application/query/{collection → legacy/v6/collection}/union.d.ts +4 -4
- package/dist/application/query/{collection → legacy/v6/collection}/union.js +15 -8
- package/dist/application/query/legacy/v6/conformance.d.ts +15 -0
- package/dist/application/query/legacy/v6/conformance.js +46 -0
- package/dist/application/query/legacy/v6/define.d.ts +37 -0
- package/dist/application/query/legacy/v6/define.js +90 -0
- package/dist/application/query/legacy/v6/execution/execute.d.ts +18 -0
- package/dist/application/query/legacy/v6/execution/execute.js +50 -0
- package/dist/application/query/legacy/v6/index.d.ts +7 -0
- package/dist/application/query/legacy/v6/index.js +3 -0
- package/dist/application/query/legacy/v6/kernel.d.ts +6 -0
- package/dist/application/query/legacy/v6/kernel.js +5 -0
- package/dist/application/query/{single → legacy/v6/single}/pagination.js +1 -1
- package/dist/application/query/{single → legacy/v6/single}/query.d.ts +2 -14
- package/dist/application/query/legacy/v6/single/query.js +1 -0
- package/dist/application/query/query.d.ts +19 -4
- package/dist/application/requirements/canonical.d.ts +7 -0
- package/dist/application/requirements/canonical.js +16 -0
- package/dist/application/requirements/classes.d.ts +9 -7
- package/dist/application/requirements/classes.js +35 -42
- package/dist/application/requirements/functions.d.ts +3 -1
- package/dist/application/requirements/functions.js +12 -27
- package/dist/application/requirements/index.d.ts +34 -16
- package/dist/application/requirements/index.js +17 -20
- package/dist/application/requirements/legacy/authority.d.ts +21 -0
- package/dist/application/requirements/{authority.js → legacy/authority.js} +5 -2
- package/dist/application/requirements/legacy/classes.d.ts +22 -0
- package/dist/application/requirements/legacy/classes.js +24 -0
- package/dist/application/requirements/legacy/core.d.ts +30 -0
- package/dist/application/requirements/{core.js → legacy/core.js} +15 -13
- package/dist/application/requirements/legacy/functions.d.ts +7 -0
- package/dist/application/requirements/legacy/functions.js +15 -0
- package/dist/application/requirements/legacy/index.d.ts +43 -0
- package/dist/application/requirements/legacy/index.js +1 -0
- package/dist/application/requirements/legacy/requirements.d.ts +31 -0
- package/dist/application/requirements/legacy/requirements.js +31 -0
- package/dist/application/requirements/requirement.d.ts +30 -19
- package/dist/application/requirements/roles.d.ts +17 -0
- package/dist/application/requirements/roles.js +62 -0
- package/dist/application/requirements/scopes.d.ts +16 -0
- package/dist/application/requirements/scopes.js +34 -0
- package/dist/application/routes/admission.d.ts +3 -3
- package/dist/application/routes/admission.js +3 -3
- package/dist/application/routes/index.d.ts +3 -2
- package/dist/application/routes/route.d.ts +3 -3
- package/dist/application/runtime/actions.js +3 -0
- package/dist/application/runtime/declarations.d.ts +6 -6
- package/dist/application/runtime/define.d.ts +5 -5
- package/dist/application/runtime/runtime.js +12 -0
- package/dist/application/runtime/workflows.d.ts +3 -1
- package/dist/application/runtime/workflows.js +3 -4
- package/dist/application/view/define.js +4 -6
- package/dist/application/view/frontend.d.ts +2 -2
- package/dist/application/view/index.d.ts +1 -1
- package/dist/application/view/route.d.ts +0 -14
- package/dist/application/view/route.js +1 -64
- package/dist/application/workflow/authoring.d.ts +3 -2
- package/dist/application/workflow/context.d.ts +8 -2
- package/dist/application/workflow/define.d.ts +4 -4
- package/dist/application/workflow/define.js +14 -9
- package/dist/application/workflow/durable.d.ts +211 -0
- package/dist/application/workflow/durable.js +1 -0
- package/dist/application/workflow/index.d.ts +3 -2
- package/dist/application/workflow/runner/inline.js +1 -0
- package/dist/application/workflow/runner/runner.d.ts +2 -2
- package/dist/application/workflow/workflow.d.ts +5 -3
- package/dist/deployment/adapter/adapter.d.ts +55 -13
- package/dist/deployment/adapter/bundle/bundle.d.ts +36 -0
- package/dist/deployment/adapter/bundle/bundle.js +1 -0
- package/dist/deployment/adapter/bundle/file.d.ts +10 -0
- package/dist/deployment/adapter/bundle/file.js +1 -0
- package/dist/deployment/adapter/bundle/index.d.ts +2 -0
- package/dist/deployment/adapter/bundle/index.js +1 -0
- package/dist/deployment/adapter/define.d.ts +4 -3
- package/dist/deployment/adapter/define.js +107 -23
- package/dist/deployment/adapter/index.d.ts +4 -3
- package/dist/deployment/adapter/index.js +1 -0
- package/dist/deployment/adapter/release/command.d.ts +33 -0
- package/dist/deployment/adapter/release/command.js +1 -0
- package/dist/deployment/adapter/release/context.d.ts +94 -0
- package/dist/deployment/adapter/release/context.js +1 -0
- package/dist/deployment/adapter/release/index.d.ts +4 -0
- package/dist/deployment/adapter/release/index.js +1 -0
- package/dist/deployment/adapter/release/list.d.ts +53 -0
- package/dist/deployment/adapter/release/list.js +1 -0
- package/dist/deployment/adapter/release/refusal.d.ts +10 -0
- package/dist/deployment/adapter/release/refusal.js +14 -0
- package/dist/deployment/adapter/release/result.d.ts +56 -0
- package/dist/deployment/adapter/release/result.js +1 -0
- package/dist/deployment/address/configuration.d.ts +96 -0
- package/dist/deployment/address/configuration.js +274 -0
- package/dist/deployment/address/fingerprint.d.ts +5 -0
- package/dist/deployment/address/fingerprint.js +27 -0
- package/dist/deployment/address/index.d.ts +5 -0
- package/dist/deployment/address/index.js +4 -0
- package/dist/deployment/address/label.d.ts +42 -0
- package/dist/deployment/address/label.js +80 -0
- package/dist/deployment/address/line.d.ts +29 -0
- package/dist/deployment/address/line.js +53 -0
- package/dist/deployment/address/record.d.ts +73 -0
- package/dist/deployment/address/record.js +138 -0
- package/dist/deployment/address/summary.d.ts +30 -0
- package/dist/deployment/address/summary.js +1 -0
- package/dist/deployment/address/vectors.d.ts +60 -0
- package/dist/deployment/address/vectors.js +517 -0
- package/dist/deployment/authoring.d.ts +0 -2
- package/dist/deployment/authoring.js +0 -1
- package/dist/deployment/build/build.d.ts +13 -2
- package/dist/deployment/build/compile.d.ts +4 -4
- package/dist/deployment/build/compile.js +31 -81
- package/dist/deployment/build/frontend/compilation.d.ts +2 -4
- package/dist/deployment/build/frontend/compilation.js +0 -5
- package/dist/deployment/build/frontend/digest.js +1 -5
- package/dist/deployment/build/index.d.ts +1 -0
- package/dist/deployment/build/index.js +1 -0
- package/dist/deployment/build/legacy/requirements.d.ts +11 -0
- package/dist/deployment/build/legacy/requirements.js +79 -0
- package/dist/deployment/build/manifest.d.ts +59 -0
- package/dist/deployment/build/manifest.js +118 -0
- package/dist/deployment/build/material.d.ts +2 -2
- package/dist/deployment/build/material.js +28 -13
- package/dist/deployment/build/schema.d.ts +2 -2
- package/dist/deployment/deployment.d.ts +3 -2
- package/dist/deployment/environment.d.ts +6 -0
- package/dist/deployment/environment.js +6 -0
- package/dist/deployment/index.d.ts +4 -6
- package/dist/deployment/index.js +1 -2
- package/dist/deployment/release/addressing.d.ts +6 -5
- package/dist/deployment/release/addressing.js +2 -3
- package/dist/deployment/release/assemble.d.ts +6 -3
- package/dist/deployment/release/assemble.js +12 -10
- package/dist/deployment/release/release.d.ts +16 -5
- package/dist/deployment/release/seal.d.ts +14 -0
- package/dist/deployment/release/seal.js +22 -0
- package/dist/deployment/release/{publication → served}/callables.d.ts +2 -2
- package/dist/deployment/release/{publication → served}/callables.js +2 -2
- package/dist/deployment/release/served/index.d.ts +11 -0
- package/dist/deployment/release/served/index.js +26 -0
- package/dist/deployment/release/{publication → served}/views.d.ts +2 -2
- package/dist/deployment/release/{publication → served}/views.js +0 -1
- package/dist/deployment/runtime/admission.d.ts +2 -2
- package/dist/deployment/runtime/admission.js +5 -5
- package/dist/deployment/verify/index.d.ts +3 -4
- package/dist/deployment/verify/index.js +2 -3
- package/dist/deployment/verify/preflight/bundle.d.ts +18 -0
- package/dist/deployment/verify/preflight/bundle.js +71 -0
- package/dist/deployment/verify/preflight/index.d.ts +1 -12
- package/dist/deployment/verify/preflight/index.js +1 -12
- package/dist/deployment/verify/readiness/fetch.d.ts +13 -0
- package/dist/deployment/verify/readiness/fetch.js +26 -0
- package/dist/deployment/verify/readiness/identity.d.ts +3 -6
- package/dist/deployment/verify/readiness/identity.js +3 -3
- package/dist/deployment/verify/readiness/index.d.ts +15 -8
- package/dist/deployment/verify/readiness/index.js +25 -6
- package/dist/deployment/verify/readiness/release.d.ts +8 -0
- package/dist/deployment/verify/readiness/release.js +22 -0
- package/dist/deployment/worker/address.d.ts +26 -0
- package/dist/deployment/worker/address.js +43 -0
- package/dist/deployment/worker/build.d.ts +60 -0
- package/dist/deployment/worker/build.js +172 -0
- package/dist/deployment/worker/configuration.d.ts +73 -0
- package/dist/deployment/worker/configuration.js +165 -0
- package/dist/deployment/worker/content.d.ts +38 -0
- package/dist/deployment/worker/content.js +169 -0
- package/dist/deployment/worker/index.d.ts +29 -0
- package/dist/deployment/worker/index.js +29 -0
- package/dist/deployment/worker/limits.d.ts +30 -0
- package/dist/deployment/worker/limits.js +30 -0
- package/dist/deployment/worker/record.d.ts +29 -0
- package/dist/deployment/worker/record.js +69 -0
- package/dist/deployment/worker/request.d.ts +118 -0
- package/dist/deployment/worker/request.js +280 -0
- package/dist/deployment/worker/response.d.ts +101 -0
- package/dist/deployment/worker/response.js +207 -0
- package/dist/execution/cache/cache.d.ts +17 -0
- package/dist/execution/cache/cache.js +11 -0
- package/dist/execution/cache/index.d.ts +2 -0
- package/dist/execution/cache/index.js +2 -0
- package/dist/execution/cache/memory.d.ts +13 -0
- package/dist/execution/cache/memory.js +48 -0
- package/dist/execution/identity/authentication.d.ts +33 -3
- package/dist/execution/identity/authentication.js +95 -36
- package/dist/execution/identity/callback.d.ts +20 -20
- package/dist/execution/identity/callback.js +34 -26
- package/dist/execution/identity/delivery.d.ts +6 -4
- package/dist/execution/identity/delivery.js +25 -20
- package/dist/execution/identity/exchange.js +11 -1
- package/dist/execution/identity/identity.d.ts +17 -3
- package/dist/execution/identity/identity.js +12 -4
- package/dist/execution/identity/jwks.d.ts +5 -0
- package/dist/execution/identity/jwks.js +92 -102
- package/dist/execution/index.d.ts +6 -4
- package/dist/execution/index.js +4 -2
- package/dist/execution/invocation/admission/age.d.ts +57 -0
- package/dist/execution/invocation/admission/age.js +208 -0
- package/dist/execution/invocation/admission/authentication.d.ts +13 -13
- package/dist/execution/invocation/admission/authentication.js +52 -44
- package/dist/execution/invocation/admission/authority.d.ts +28 -6
- package/dist/execution/invocation/admission/authority.js +9 -2
- package/dist/execution/invocation/admission/index.d.ts +4 -3
- package/dist/execution/invocation/admission/index.js +3 -2
- package/dist/execution/invocation/admission/input.d.ts +2 -2
- package/dist/execution/invocation/admission/input.js +16 -2
- package/dist/execution/invocation/admission/target.d.ts +11 -0
- package/dist/execution/invocation/admission/target.js +22 -3
- package/dist/execution/invocation/capabilities/bind.d.ts +14 -0
- package/dist/execution/invocation/capabilities/bind.js +74 -0
- package/dist/execution/invocation/capabilities/index.d.ts +1 -0
- package/dist/execution/invocation/capabilities/index.js +1 -0
- package/dist/execution/invocation/dependency/bind.d.ts +3 -1
- package/dist/execution/invocation/dependency/bind.js +36 -16
- package/dist/execution/invocation/dispatch/action.js +4 -2
- package/dist/execution/invocation/dispatch/context.d.ts +8 -7
- package/dist/execution/invocation/dispatch/context.js +34 -45
- package/dist/execution/invocation/dispatch/workflow.js +4 -6
- package/dist/execution/invocation/handler.js +8 -2
- package/dist/execution/invocation/index.d.ts +2 -2
- package/dist/execution/invocation/index.js +1 -1
- package/dist/execution/invocation/integration/authentication.d.ts +3 -3
- package/dist/execution/invocation/integration/authentication.js +7 -7
- package/dist/execution/invocation/integration/call.d.ts +2 -1
- package/dist/execution/invocation/integration/call.js +3 -3
- package/dist/execution/invocation/integration/clients.d.ts +1 -1
- package/dist/execution/invocation/integration/index.d.ts +1 -0
- package/dist/execution/invocation/integration/index.js +1 -0
- package/dist/execution/invocation/invocation.d.ts +6 -0
- package/dist/execution/invocation/invocation.js +130 -22
- package/dist/execution/invocation/lifecycle/active.d.ts +8 -2
- package/dist/execution/invocation/lifecycle/active.js +3 -3
- package/dist/execution/invocation/lifecycle/index.d.ts +1 -1
- package/dist/execution/invocation/result/errors.d.ts +0 -10
- package/dist/execution/invocation/result/errors.js +12 -16
- package/dist/execution/invocation/result/index.d.ts +3 -2
- package/dist/execution/invocation/result/index.js +2 -1
- package/dist/execution/invocation/result/project.js +41 -1
- package/dist/execution/invocation/result/undeclared.d.ts +7 -0
- package/dist/execution/invocation/result/undeclared.js +18 -0
- package/dist/execution/node/serve.d.ts +2 -2
- package/dist/execution/node/serve.js +1 -1
- package/dist/execution/runtime/index.d.ts +1 -0
- package/dist/execution/runtime/index.js +1 -0
- package/dist/execution/runtime/load.d.ts +3 -3
- package/dist/execution/runtime/load.js +3 -2
- package/dist/execution/runtime/release.d.ts +17 -0
- package/dist/execution/runtime/release.js +7 -0
- package/dist/execution/serve.d.ts +18 -4
- package/dist/execution/serve.js +10 -0
- package/dist/execution/service/create.js +43 -7
- package/dist/execution/service/initialization.d.ts +4 -4
- package/dist/execution/service/initialization.js +23 -14
- package/dist/execution/service/release.d.ts +2 -2
- package/dist/execution/service/release.js +3 -2
- package/dist/execution/service/service.d.ts +20 -5
- package/dist/execution/service/serving/delivery.d.ts +5 -0
- package/dist/execution/service/{publication → serving}/delivery.js +4 -1
- package/dist/execution/service/{publication → serving}/index.d.ts +1 -1
- package/dist/execution/service/serving/installation.d.ts +4 -0
- package/dist/execution/service/serving/installation.js +9 -0
- package/dist/execution/service/serving/source.d.ts +11 -0
- package/dist/execution/service/serving/source.js +15 -0
- package/dist/execution/workflows/attempts.d.ts +87 -0
- package/dist/execution/workflows/attempts.js +205 -0
- package/dist/execution/workflows/discovery.d.ts +14 -0
- package/dist/execution/workflows/discovery.js +151 -0
- package/dist/execution/workflows/engine.d.ts +83 -0
- package/dist/execution/workflows/engine.js +1 -0
- package/dist/execution/workflows/envelope.d.ts +12 -0
- package/dist/execution/workflows/envelope.js +46 -0
- package/dist/execution/workflows/failure.d.ts +56 -0
- package/dist/execution/workflows/failure.js +204 -0
- package/dist/execution/workflows/index.d.ts +4 -0
- package/dist/execution/workflows/index.js +3 -0
- package/dist/execution/workflows/integrations.d.ts +13 -0
- package/dist/execution/workflows/integrations.js +25 -0
- package/dist/execution/workflows/options.d.ts +81 -0
- package/dist/execution/workflows/options.js +158 -0
- package/dist/execution/workflows/receiver.d.ts +24 -0
- package/dist/execution/workflows/receiver.js +99 -0
- package/dist/execution/workflows/route.d.ts +12 -0
- package/dist/execution/workflows/route.js +35 -0
- package/dist/execution/workflows/run.d.ts +23 -0
- package/dist/execution/workflows/run.js +369 -0
- package/dist/execution/workflows/steps.d.ts +48 -0
- package/dist/execution/workflows/steps.js +93 -0
- package/dist/index.d.ts +5 -5
- package/dist/index.js +2 -2
- package/dist/platform/graph/alias.d.ts +1 -5
- package/dist/platform/graph/alias.js +1 -5
- package/dist/platform/graph/document/index.d.ts +1 -1
- package/dist/platform/graph/document/index.js +1 -1
- package/dist/platform/graph/index.d.ts +1 -1
- package/dist/platform/graph/index.js +1 -1
- package/dist/platform/release/index.d.ts +2 -0
- package/dist/platform/release/index.js +2 -0
- package/dist/platform/schema/callable-authoring.d.ts +21 -0
- package/dist/platform/schema/callable-authoring.js +27 -0
- package/dist/platform/schema/class-authoring.d.ts +58 -12
- package/dist/platform/schema/class-authoring.js +38 -4
- package/dist/platform/schema/class-icon-svg.d.ts +9 -0
- package/dist/platform/schema/class-icon-svg.js +29 -0
- package/dist/platform/schema/class-icon.d.ts +3 -8
- package/dist/platform/schema/class-icon.js +2 -29
- package/dist/platform/schema/index.d.ts +11 -4
- package/dist/platform/schema/index.js +2 -1
- package/dist/platform/schema/kernel-compiled.d.ts +2 -0
- package/dist/platform/schema/kernel-compiled.js +2 -0
- package/dist/platform/schema/kernel.d.ts +4 -2
- package/dist/platform/schema/property.d.ts +5 -0
- package/dist/platform/schema/references/index.d.ts +6 -0
- package/dist/platform/schema/references/index.js +1 -0
- package/dist/platform/schema/schema-authoring.d.ts +14 -7
- package/dist/platform/schema/schema-authoring.js +5 -1
- package/dist/platform/versioning/dependents.d.ts +18 -0
- package/dist/platform/versioning/dependents.js +15 -0
- package/dist/platform/versioning/index.d.ts +5 -0
- package/dist/platform/versioning/index.js +5 -0
- package/dist/platform/versioning/name.d.ts +38 -0
- package/dist/platform/versioning/name.js +58 -0
- package/dist/platform/versioning/reference.d.ts +48 -0
- package/dist/platform/versioning/reference.js +95 -0
- package/dist/platform/versioning/version.d.ts +72 -0
- package/dist/platform/versioning/version.js +98 -0
- package/dist/project/admit.js +1 -5
- package/dist/project/define.d.ts +4 -4
- package/dist/project/define.js +55 -35
- package/dist/project/index.d.ts +1 -1
- package/dist/project/install-command.d.ts +6 -0
- package/dist/project/install-command.js +9 -0
- package/dist/project/project.d.ts +10 -8
- package/dist/testing/dataset/define.d.ts +1 -1
- package/dist/testing/durable/engine.d.ts +128 -0
- package/dist/testing/durable/engine.js +619 -0
- package/dist/testing/durable/index.d.ts +3 -0
- package/dist/testing/durable/index.js +1 -0
- package/dist/testing/durable/steps.d.ts +30 -0
- package/dist/testing/durable/steps.js +45 -0
- package/dist/testing/file.d.ts +20 -0
- package/dist/testing/file.js +49 -0
- package/dist/testing/index.d.ts +10 -1
- package/dist/testing/index.js +7 -1
- package/dist/testing/load.js +1 -1
- package/dist/testing/query.d.ts +22 -0
- package/dist/testing/query.js +36 -0
- package/dist/tooling/cli/adapter-command.d.ts +35 -0
- package/dist/tooling/cli/adapter-command.js +66 -0
- package/dist/tooling/cli/arguments.d.ts +17 -6
- package/dist/tooling/cli/arguments.js +175 -52
- package/dist/tooling/cli/build.d.ts +55 -0
- package/dist/tooling/cli/build.js +77 -0
- package/dist/tooling/cli/bun.d.ts +0 -1
- package/dist/tooling/cli/bun.js +0 -7
- package/dist/tooling/cli/commit.d.ts +35 -0
- package/dist/tooling/cli/commit.js +235 -0
- package/dist/tooling/cli/deploy-mode.d.ts +26 -0
- package/dist/tooling/cli/deploy-mode.js +59 -0
- package/dist/tooling/cli/deploy-result.d.ts +80 -0
- package/dist/tooling/cli/deploy-result.js +64 -0
- package/dist/tooling/cli/diff/declared.d.ts +7 -0
- package/dist/tooling/cli/diff/declared.js +27 -0
- package/dist/tooling/cli/diff/index.d.ts +30 -0
- package/dist/tooling/cli/diff/index.js +58 -0
- package/dist/tooling/cli/diff/render.d.ts +15 -0
- package/dist/tooling/cli/diff/render.js +131 -0
- package/dist/tooling/cli/diff/report.d.ts +88 -0
- package/dist/tooling/cli/diff/report.js +154 -0
- package/dist/tooling/cli/dotenv.d.ts +5 -5
- package/dist/tooling/cli/dotenv.js +6 -36
- package/dist/tooling/cli/help.js +173 -60
- package/dist/tooling/cli/immutable-deployment.d.ts +83 -0
- package/dist/tooling/cli/immutable-deployment.js +135 -0
- package/dist/tooling/cli/index.d.ts +12 -4
- package/dist/tooling/cli/index.js +6 -3
- package/dist/tooling/cli/installed-on.d.ts +83 -0
- package/dist/tooling/cli/installed-on.js +156 -0
- package/dist/tooling/cli/list.d.ts +152 -0
- package/dist/tooling/cli/list.js +331 -0
- package/dist/tooling/cli/log.d.ts +5 -2
- package/dist/tooling/cli/log.js +9 -2
- package/dist/tooling/cli/orchestrate.d.ts +0 -6
- package/dist/tooling/cli/orchestrate.js +252 -91
- package/dist/tooling/cli/project.d.ts +3 -3
- package/dist/tooling/cli/publish/index.d.ts +81 -0
- package/dist/tooling/cli/publish/index.js +383 -0
- package/dist/tooling/cli/publish/report.d.ts +49 -0
- package/dist/tooling/cli/publish/report.js +15 -0
- package/dist/tooling/cli/registry/client.d.ts +121 -0
- package/dist/tooling/cli/registry/client.js +354 -0
- package/dist/tooling/cli/registry/error.d.ts +11 -0
- package/dist/tooling/cli/registry/error.js +17 -0
- package/dist/tooling/cli/registry/executable.d.ts +35 -0
- package/dist/tooling/cli/registry/executable.js +96 -0
- package/dist/tooling/cli/registry/index.d.ts +9 -0
- package/dist/tooling/cli/registry/index.js +8 -0
- package/dist/tooling/cli/registry/installations.d.ts +67 -0
- package/dist/tooling/cli/registry/installations.js +108 -0
- package/dist/tooling/cli/registry/process.d.ts +36 -0
- package/dist/tooling/cli/registry/process.js +119 -0
- package/dist/tooling/cli/secrets.d.ts +9 -0
- package/dist/tooling/cli/secrets.js +19 -0
- package/dist/tooling/cli/yank.d.ts +34 -0
- package/dist/tooling/cli/yank.js +32 -0
- package/dist/tooling/linter/adapters/typescript/definition-calls.d.ts +34 -0
- package/dist/tooling/linter/adapters/typescript/definition-calls.js +88 -0
- package/dist/tooling/linter/adapters/typescript/discover.js +8 -2
- package/dist/tooling/linter/adapters/typescript/imports.d.ts +0 -1
- package/dist/tooling/linter/adapters/typescript/imports.js +1 -5
- package/dist/tooling/linter/adapters/typescript/index.d.ts +9 -2
- package/dist/tooling/linter/adapters/typescript/index.js +4 -2
- package/dist/tooling/linter/adapters/typescript/legacy.d.ts +20 -0
- package/dist/tooling/linter/adapters/typescript/legacy.js +28 -0
- package/dist/tooling/linter/adapters/typescript/query-observation.js +37 -12
- package/dist/tooling/linter/adapters/typescript/syntax.d.ts +3 -3
- package/dist/tooling/linter/adapters/typescript/syntax.js +13 -25
- package/dist/tooling/linter/adapters/typescript/type-analysis.d.ts +2 -0
- package/dist/tooling/linter/adapters/typescript/type-analysis.js +10 -0
- package/dist/tooling/linter/implementations/source/callable-requirements.d.ts +2 -4
- package/dist/tooling/linter/implementations/source/callable-requirements.js +16 -58
- package/dist/tooling/linter/implementations/source/const-initializer.d.ts +3 -0
- package/dist/tooling/linter/implementations/source/const-initializer.js +31 -0
- package/dist/tooling/linter/implementations/source/definitions.d.ts +2 -0
- package/dist/tooling/linter/implementations/source/definitions.js +425 -0
- package/dist/tooling/linter/implementations/source/dependencies.js +13 -72
- package/dist/tooling/linter/implementations/source/domain-requirements.d.ts +8 -0
- package/dist/tooling/linter/implementations/source/domain-requirements.js +35 -0
- package/dist/tooling/linter/implementations/source/global.js +39 -19
- package/dist/tooling/linter/implementations/source/legacy/requirements.d.ts +10 -0
- package/dist/tooling/linter/implementations/source/legacy/requirements.js +40 -0
- package/dist/tooling/linter/implementations/source/legacy-folders.d.ts +3 -0
- package/dist/tooling/linter/implementations/source/legacy-folders.js +126 -0
- package/dist/tooling/linter/implementations/source/mutations.js +153 -70
- package/dist/tooling/linter/implementations/source/policy-edges.d.ts +2 -0
- package/dist/tooling/linter/implementations/source/policy-edges.js +113 -0
- package/dist/tooling/linter/implementations/source/providers.js +5 -5
- package/dist/tooling/linter/implementations/source/queries.js +1 -17
- package/dist/tooling/linter/implementations/source/requirement-entries.d.ts +24 -0
- package/dist/tooling/linter/implementations/source/requirement-entries.js +52 -0
- package/dist/tooling/linter/implementations/source/runtime-imports.d.ts +2 -0
- package/dist/tooling/linter/implementations/source/runtime-imports.js +119 -0
- package/dist/tooling/linter/implementations/source/schema.d.ts +3 -0
- package/dist/tooling/linter/implementations/source/schema.js +9 -5
- package/dist/tooling/linter/implementations/source/shared.d.ts +19 -5
- package/dist/tooling/linter/implementations/source/shared.js +131 -55
- package/dist/tooling/linter/implementations/source/tests.js +1 -1
- package/dist/tooling/linter/implementations/source/verifiers.js +8 -2
- package/dist/tooling/linter/implementations/source/views.js +2 -2
- package/dist/tooling/linter/implementations/source/workflows.js +499 -17
- package/dist/tooling/linter/policy/generated.js +18 -67
- package/dist/tooling/linter/requirements/registry.js +14 -9
- package/dist/tooling/packaging/declarations/ownership.js +1 -1
- package/dist/tooling/packaging/finalize.d.ts +1 -1
- package/dist/tooling/packaging/finalize.js +1 -1
- package/docs/accounts/scenarios.tsv +12 -0
- package/docs/admission-age.md +88 -0
- package/docs/auth-api-migration.md +57 -0
- package/docs/business-errors.md +42 -0
- package/docs/domain-definition-migration.md +44 -0
- package/docs/domain-schema-migration.md +36 -0
- package/docs/durable-workflows.md +530 -0
- package/docs/handler-dependencies.md +381 -0
- package/docs/legacy/query-v6.md +62 -0
- package/docs/legacy.md +113 -0
- package/docs/queries.md +493 -0
- package/docs/release.md +155 -0
- package/docs/requirements.md +143 -0
- package/docs/schema-cost.md +124 -0
- package/package.json +62 -26
- package/dist/application/application.d.ts +0 -28
- package/dist/application/query/execution/projection.d.ts +0 -3
- package/dist/application/query/execution/projection.js +0 -3
- package/dist/application/requirements/authority.d.ts +0 -7
- package/dist/application/requirements/core.d.ts +0 -14
- package/dist/deployment/adapter/deploy/context.d.ts +0 -15
- package/dist/deployment/adapter/deploy/index.d.ts +0 -2
- package/dist/deployment/adapter/deploy/result.d.ts +0 -50
- package/dist/deployment/adapter/prepare/artifact.d.ts +0 -33
- package/dist/deployment/adapter/prepare/context.d.ts +0 -23
- package/dist/deployment/adapter/prepare/index.d.ts +0 -2
- package/dist/deployment/deploy.d.ts +0 -20
- package/dist/deployment/deploy.js +0 -31
- package/dist/deployment/release/publication/index.d.ts +0 -6
- package/dist/deployment/release/publication/index.js +0 -6
- package/dist/deployment/release/publication/manifest.d.ts +0 -3
- package/dist/deployment/release/publication/manifest.js +0 -5
- package/dist/deployment/release/publication/requirements.d.ts +0 -3
- package/dist/deployment/release/publication/requirements.js +0 -3
- package/dist/deployment/release/publication/seal.d.ts +0 -10
- package/dist/deployment/release/publication/seal.js +0 -39
- package/dist/deployment/verify/preflight/artifact.d.ts +0 -6
- package/dist/deployment/verify/preflight/artifact.js +0 -122
- package/dist/deployment/verify/preflight/publication.d.ts +0 -4
- package/dist/deployment/verify/preflight/publication.js +0 -14
- package/dist/deployment/verify/readiness/deployment.d.ts +0 -3
- package/dist/deployment/verify/readiness/deployment.js +0 -151
- package/dist/deployment/verify/readiness/publication.d.ts +0 -11
- package/dist/deployment/verify/readiness/publication.js +0 -41
- package/dist/execution/service/errors.d.ts +0 -3
- package/dist/execution/service/errors.js +0 -3
- package/dist/execution/service/publication/delivery.d.ts +0 -2
- package/dist/execution/service/publication/installation.d.ts +0 -3
- package/dist/execution/service/publication/installation.js +0 -8
- package/dist/execution/service/publication/source.d.ts +0 -3
- package/dist/execution/service/publication/source.js +0 -11
- package/dist/platform/publication/index.d.ts +0 -2
- package/dist/platform/publication/index.js +0 -2
- package/dist/tooling/cli/astrale/authority.d.ts +0 -5
- package/dist/tooling/cli/astrale/authority.js +0 -11
- package/dist/tooling/cli/astrale/executable.d.ts +0 -2
- package/dist/tooling/cli/astrale/executable.js +0 -47
- package/dist/tooling/cli/astrale/failure.d.ts +0 -6
- package/dist/tooling/cli/astrale/failure.js +0 -48
- package/dist/tooling/cli/astrale/instance.d.ts +0 -11
- package/dist/tooling/cli/astrale/instance.js +0 -52
- package/dist/tooling/cli/astrale/process.d.ts +0 -13
- package/dist/tooling/cli/astrale/process.js +0 -94
- package/dist/tooling/cli/astrale/version.d.ts +0 -18
- package/dist/tooling/cli/astrale/version.js +0 -55
- package/dist/tooling/cli/credential.d.ts +0 -2
- package/dist/tooling/cli/credential.js +0 -57
- package/dist/tooling/cli/deprecations.d.ts +0 -9
- package/dist/tooling/cli/deprecations.js +0 -15
- package/dist/tooling/cli/development/candidate.d.ts +0 -25
- package/dist/tooling/cli/development/candidate.js +0 -176
- package/dist/tooling/cli/development/deployment.d.ts +0 -16
- package/dist/tooling/cli/development/deployment.js +0 -39
- package/dist/tooling/cli/development/develop.d.ts +0 -11
- package/dist/tooling/cli/development/develop.js +0 -243
- package/dist/tooling/cli/development/lease.d.ts +0 -18
- package/dist/tooling/cli/development/lease.js +0 -163
- package/dist/tooling/cli/development/lifecycle.d.ts +0 -9
- package/dist/tooling/cli/development/lifecycle.js +0 -43
- package/dist/tooling/cli/development/project-imports.d.ts +0 -22
- package/dist/tooling/cli/development/project-imports.js +0 -39
- package/dist/tooling/cli/development/project-lock.d.ts +0 -16
- package/dist/tooling/cli/development/project-lock.js +0 -41
- package/dist/tooling/cli/development/rebuild.d.ts +0 -13
- package/dist/tooling/cli/development/rebuild.js +0 -58
- package/dist/tooling/cli/development/release-evidence.d.ts +0 -4
- package/dist/tooling/cli/development/release-evidence.js +0 -10
- package/dist/tooling/cli/development/report.d.ts +0 -6
- package/dist/tooling/cli/development/report.js +0 -14
- package/dist/tooling/cli/development/session-file.d.ts +0 -53
- package/dist/tooling/cli/development/session-file.js +0 -337
- package/dist/tooling/cli/development/source-watch.d.ts +0 -14
- package/dist/tooling/cli/development/source-watch.js +0 -140
- package/dist/tooling/cli/development/sources.d.ts +0 -7
- package/dist/tooling/cli/development/sources.js +0 -48
- package/dist/tooling/cli/development/target-lock.d.ts +0 -16
- package/dist/tooling/cli/development/target-lock.js +0 -68
- package/dist/tooling/cli/development/view.d.ts +0 -28
- package/dist/tooling/cli/development/view.js +0 -151
- package/dist/tooling/cli/environment-release.d.ts +0 -21
- package/dist/tooling/cli/environment-release.js +0 -46
- package/dist/tooling/cli/evidence.d.ts +0 -11
- package/dist/tooling/cli/evidence.js +0 -53
- package/dist/tooling/cli/installation/index.d.ts +0 -2
- package/dist/tooling/cli/installation/index.js +0 -1
- package/dist/tooling/cli/installation/observation.d.ts +0 -10
- package/dist/tooling/cli/installation/observation.js +0 -44
- package/dist/tooling/cli/installation/reconcile.d.ts +0 -32
- package/dist/tooling/cli/installation/reconcile.js +0 -122
- package/dist/tooling/linter/implementations/source/migrations.d.ts +0 -2
- package/dist/tooling/linter/implementations/source/migrations.js +0 -113
- package/dist/tooling/linter/qualification/index.d.ts +0 -10
- package/dist/tooling/linter/qualification/index.js +0 -2
- package/dist/tooling/linter/qualification/query-fixtures.d.ts +0 -2
- package/dist/tooling/linter/qualification/query-fixtures.js +0 -68
- package/dist/tooling/linter/qualification/runner.d.ts +0 -3
- package/dist/tooling/linter/qualification/runner.js +0 -6
- /package/dist/application/{application.js → domain.js} +0 -0
- /package/dist/application/{query/single/query.js → mutation/legacy/v6/builder.js} +0 -0
- /package/dist/{deployment/adapter/deploy/context.js → application/mutation/legacy/v6/mutation.js} +0 -0
- /package/dist/application/mutation/{authoring → legacy/v6}/precondition.js +0 -0
- /package/dist/{deployment/adapter/deploy/index.js → application/query/answer/answer.js} +0 -0
- /package/dist/{deployment/adapter/deploy/result.js → application/query/defined/query.js} +0 -0
- /package/dist/{deployment/adapter/prepare/artifact.js → application/query/execution/client.js} +0 -0
- /package/dist/{deployment/adapter/prepare/context.js → application/query/handles/conditions.js} +0 -0
- /package/dist/{deployment/adapter/prepare/index.js → application/query/handles/domain.js} +0 -0
- /package/dist/application/query/{collection → legacy/v6/collection}/identity.js +0 -0
- /package/dist/application/query/{collection → legacy/v6/collection}/limits.d.ts +0 -0
- /package/dist/application/query/{collection → legacy/v6/collection}/limits.js +0 -0
- /package/dist/application/query/{collection → legacy/v6/collection}/metadata.js +0 -0
- /package/dist/application/query/{execution → legacy/v6/execution}/pages.d.ts +0 -0
- /package/dist/application/query/{execution → legacy/v6/execution}/pages.js +0 -0
- /package/dist/application/query/{single → legacy/v6/single}/index.d.ts +0 -0
- /package/dist/application/query/{single → legacy/v6/single}/index.js +0 -0
- /package/dist/application/query/{single → legacy/v6/single}/node.d.ts +0 -0
- /package/dist/application/query/{single → legacy/v6/single}/node.js +0 -0
- /package/dist/application/query/{single → legacy/v6/single}/pagination.d.ts +0 -0
- /package/dist/application/query/{single → legacy/v6/single}/selection.d.ts +0 -0
- /package/dist/application/query/{single → legacy/v6/single}/selection.js +0 -0
- /package/dist/deployment/release/{publication → served}/routes.d.ts +0 -0
- /package/dist/deployment/release/{publication → served}/routes.js +0 -0
- /package/dist/execution/service/{publication → serving}/index.js +0 -0
package/docs/queries.md
ADDED
|
@@ -0,0 +1,493 @@
|
|
|
1
|
+
# Queries
|
|
2
|
+
|
|
3
|
+
A Query is a typed business observation over the graph. Its guarantees:
|
|
4
|
+
|
|
5
|
+
- **Typed by the Domain.** Handles, conditions, rows and answers are typed from the Domain's
|
|
6
|
+
Schema. A Class, Property or relation the Domain cannot name does not compile.
|
|
7
|
+
- **Bounded before it reads.** Every verb carries its bound. Before anything is sent, the SDK
|
|
8
|
+
refuses a Query past its bounds, and a relation that crosses a dependency Class the Domain does
|
|
9
|
+
not declare.
|
|
10
|
+
- **One snapshot per read.** Each read is one Kernel invocation at its own snapshot. Facets,
|
|
11
|
+
steps and pages of one Query share none. A read whose root lists more than 32,768 ids in
|
|
12
|
+
`id.in` is the exception: the SDK sends it in consecutive parts, each at its own snapshot, and
|
|
13
|
+
merges their rows in the Kernel's order.
|
|
14
|
+
- **Authority-neutral.** A Query names no authority; each call names the authority it reads
|
|
15
|
+
under.
|
|
16
|
+
- **One error per refusal.** A read the SDK or the Kernel refuses raises one `QueryError` by code.
|
|
17
|
+
A network failure, and a refusal that says when to retry, pass as they came. Business refusals
|
|
18
|
+
are the Query's declared errors.
|
|
19
|
+
|
|
20
|
+
A Query reads on a Host whose Kernel serves Query v7 and the Class of each row. A Kernel that
|
|
21
|
+
refuses Query v7 by name raises `QueryError` `UNSUPPORTED` with `feature: 'v7'`; a Runtime that
|
|
22
|
+
does not name that refusal answers `REFUSED`, with `kernelCode: 'INTERNAL_ERROR'`. An answer that
|
|
23
|
+
leaves out a row's Class raises `UNSUPPORTED` with `feature: 'classes'`. Query v7 is not served
|
|
24
|
+
in maintenance or repair sessions: the Kernel refuses it with `INSTANCE_MAINTENANCE`, which passes
|
|
25
|
+
as it came, and a migration that runs there reads with [Query V6](legacy/query-v6.md).
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import type { NodeId } from '@astrale-os/sdk/graph/node'
|
|
29
|
+
import { defineQuery } from '@astrale-os/sdk/query'
|
|
30
|
+
import { z } from 'zod'
|
|
31
|
+
|
|
32
|
+
import type { schema } from '#schema'
|
|
33
|
+
|
|
34
|
+
export const articleWithComments = defineQuery<typeof schema>()('publishing.article.with-comments', {
|
|
35
|
+
build: (article: NodeId, d) =>
|
|
36
|
+
d.Article.with((a) => ({
|
|
37
|
+
author: a.author.find(),
|
|
38
|
+
pinned: a
|
|
39
|
+
.via(d.comment_on, { direction: 'incoming' })
|
|
40
|
+
.where((_comment, edge) => edge.pinned.eq(true))
|
|
41
|
+
.orderBy((comment) => comment.postedAt.desc())
|
|
42
|
+
.first(3),
|
|
43
|
+
comments: a.via(d.comment_on, { direction: 'incoming' }).count({ upTo: 1_000 }),
|
|
44
|
+
})).find(article),
|
|
45
|
+
output: (row, article, { error }) => {
|
|
46
|
+
if (row === undefined) throw error('ARTICLE_NOT_FOUND', { article })
|
|
47
|
+
return row
|
|
48
|
+
},
|
|
49
|
+
errors: {
|
|
50
|
+
ARTICLE_NOT_FOUND: {
|
|
51
|
+
family: 'NOT_FOUND',
|
|
52
|
+
message: 'The article does not exist.',
|
|
53
|
+
details: z.strictObject({ article: z.string() }),
|
|
54
|
+
},
|
|
55
|
+
},
|
|
56
|
+
})
|
|
57
|
+
|
|
58
|
+
// In an Action that declares `errors: { ...articleWithComments.errors }`
|
|
59
|
+
const article = await query(articleWithComments, input.article, { as: 'caller' })
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Handles
|
|
63
|
+
|
|
64
|
+
`build(input, d)` receives the handles of the Domain:
|
|
65
|
+
|
|
66
|
+
| Handle | What it reads |
|
|
67
|
+
| --- | --- |
|
|
68
|
+
| `d.Article` | A Node Class of the Domain. An Edge Class handle (`d.comment_on`) reads Edges at the root. |
|
|
69
|
+
| `d.directory.Person` | A Class of the dependency the Schema aliases `directory`. |
|
|
70
|
+
| `d.kernel.<Class>` | A Kernel Class. |
|
|
71
|
+
| `d.core.<node>` | A Core node of the Domain, as a target: `get(d.core.settings)`, `rel.is(d.core.settings)`. |
|
|
72
|
+
| `d.origin` | The Domain's origin. |
|
|
73
|
+
| `d.document(query)` | One canonical v7 document; see [Canonical documents](#canonical-documents). |
|
|
74
|
+
|
|
75
|
+
A Class or alias named `kernel`, `core`, `origin` or `document` has no handle.
|
|
76
|
+
|
|
77
|
+
## Reads
|
|
78
|
+
|
|
79
|
+
A read starts from a Class handle, is narrowed with `where`, ordered with `orderBy`, carries
|
|
80
|
+
relations with `with`, and ends with the verb that says how much it reads:
|
|
81
|
+
|
|
82
|
+
| Verb | Answers | Refusals |
|
|
83
|
+
| --- | --- | --- |
|
|
84
|
+
| `get(id?)` | Exactly one row | None: `NOT_FOUND`. A second: `INTEGRITY`. One the reader may not read: `NOT_READABLE`. |
|
|
85
|
+
| `find(id?)` | One row, or `undefined` | A second: `INTEGRITY`. One the reader may not read: `NOT_READABLE`. |
|
|
86
|
+
| `first()` | The first row, or `undefined` | |
|
|
87
|
+
| `first(n)` | Up to `n` rows | |
|
|
88
|
+
| `first(n, { more: true })` | `{ rows, more }`, reading `n + 1` rows | |
|
|
89
|
+
| `page({ max })` | `{ rows, next? }`; only as a Query's single read | |
|
|
90
|
+
| `all({ max })` | Every row | Past `max`: `TOO_MANY`. |
|
|
91
|
+
| `exists(id?)` | `boolean` | |
|
|
92
|
+
| `count({ upTo })` | `{ count, more }`; `more` says the count reached `upTo` | |
|
|
93
|
+
|
|
94
|
+
`get` asserts that the row exists, so it reads the ids the Domain itself holds; for an id a caller
|
|
95
|
+
sends, use `find` and raise a declared error from `output` (see [Errors](#errors)).
|
|
96
|
+
|
|
97
|
+
`id` is a `NodeId`, a `NodePath` or a Core node. `.ref()` renders rows as references,
|
|
98
|
+
`{ id, $class }`. `.includeWithheld()` keeps the rows the reader may not read in a list, as
|
|
99
|
+
`{ id, $class, $withheld }` naming the values withheld. `get` and `find` raise `NOT_READABLE` on
|
|
100
|
+
such a row, since it exists. `d.A.union(d.B)` reads the Nodes of both Classes.
|
|
101
|
+
|
|
102
|
+
### Conditions
|
|
103
|
+
|
|
104
|
+
`where` takes one condition or a list, an implicit `and`. A falsy entry of the list is skipped, so
|
|
105
|
+
an optional filter is written in place:
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
d.Article.where((a) => [
|
|
109
|
+
a.state.eq('published'),
|
|
110
|
+
filter.author && a.author.is(filter.author),
|
|
111
|
+
filter.since && a.publishedAt.gte(filter.since),
|
|
112
|
+
filter.featured !== undefined && a.featured.eq(filter.featured),
|
|
113
|
+
])
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
A filter whose value may be `false` or `0` is written `filter.x !== undefined && …` when it
|
|
117
|
+
applies whenever the caller sends it: with `filter.x && …`, those values would skip the entry. When
|
|
118
|
+
`false` means no filter, say so: `filter.x ? a.x.eq(true) : undefined`.
|
|
119
|
+
|
|
120
|
+
| Term | Meaning |
|
|
121
|
+
| --- | --- |
|
|
122
|
+
| `p.eq(v)` | Equal. `eq(null)` matches a stored null. |
|
|
123
|
+
| `p.in(values)` | One of at most 16 values. |
|
|
124
|
+
| `node.id.eq(id)`, `node.id.in(ids)` | The Node is this one, or one of these. `id.in` takes any length at a read's root; elsewhere a read carries at most 32,768 ids and values. |
|
|
125
|
+
| `node.path.eq(path)`, `node.path.in(paths)` | The Node is at this path, or at one of these. |
|
|
126
|
+
| `p.isSet()`, `p.isMissing()` | The value is present, or absent. |
|
|
127
|
+
| `p.gt`, `p.gte`, `p.lt`, `p.lte` | Ranges, on text, numbers and open values. |
|
|
128
|
+
| `p.between(lower, upper)` | `lower <= value < upper`. |
|
|
129
|
+
| `p.startsWith(prefix)` | A text prefix. |
|
|
130
|
+
| `node.is(Class)`, `node.isExactly(Class)` | The Node is of the Class, or a subclass for `is`. It narrows the handle and the rows. |
|
|
131
|
+
| `node.is(Class, (n) => conditions)` | The Node is of the Class and meets conditions written on the narrowed handle. |
|
|
132
|
+
| `c.and(…)`, `c.or(…)`, `c.not()` | Combinators on any condition. |
|
|
133
|
+
|
|
134
|
+
A relation is a condition too:
|
|
135
|
+
|
|
136
|
+
| Term | Meaning |
|
|
137
|
+
| --- | --- |
|
|
138
|
+
| `rel.is(target)` | The relation reaches this Node. |
|
|
139
|
+
| `rel.exists()` | It reaches any Node. |
|
|
140
|
+
| `rel.some(cond?)`, `rel.none(cond?)`, `rel.every(cond)` | Over the Nodes it reaches. |
|
|
141
|
+
| `rel.atLeast(n, cond?)`, `rel.atMost(n, cond?)`, `rel.exactly(n, cond?)` | How many it reaches. |
|
|
142
|
+
|
|
143
|
+
The callback of a relation condition receives `(node, edge)`: conditions on the far Node and on
|
|
144
|
+
the Edge's Properties.
|
|
145
|
+
|
|
146
|
+
### Order
|
|
147
|
+
|
|
148
|
+
`orderBy` takes one key or a list: `orderBy((a) => [a.publishedAt.desc(), a.title.asc()])`. Rows
|
|
149
|
+
without the value sort last; `asc({ missing: 'first' })` sorts them first. On a union whose
|
|
150
|
+
Classes map one name to different Properties, the name filters but does not order.
|
|
151
|
+
|
|
152
|
+
### Relations
|
|
153
|
+
|
|
154
|
+
A to-one end is named by its far role: `a.author` reads the author of an Article. Any Edge is read
|
|
155
|
+
with `.via(edge, { direction })`, where `direction` is `outgoing`, `incoming` or `incident`.
|
|
156
|
+
`.via([e1, e2])` reads several Edge Classes. `direction` is required when both ends accept the
|
|
157
|
+
Class, or when the Edges listed leave it in different directions.
|
|
158
|
+
|
|
159
|
+
A relation reads with the root verbs, per parent row: `get`, `find`, `first`,
|
|
160
|
+
`first(n, { more: true })`, `all`, `count` and `exists`. A relation's `get` that finds none, or a second row, raises `INTEGRITY` naming the
|
|
161
|
+
relation. A relation also takes `where`, `orderBy`, `with`, `ref`, `includeWithheld`, `distinct`
|
|
162
|
+
and `withEdge()`, which adds the Edge's Class and Properties to each row under `$edge`.
|
|
163
|
+
|
|
164
|
+
`.with((a) => ({ name: read }))` adds each relation's answer to the row under the name given. A
|
|
165
|
+
name a row already carries does not compile, and neither does a `.with` that reads another root:
|
|
166
|
+
read it as a facet of the Query.
|
|
167
|
+
|
|
168
|
+
### Rows
|
|
169
|
+
|
|
170
|
+
A Node row is portable JSON: `id`, `$class`, and every Property by name. An optional Property may
|
|
171
|
+
be absent; `null` is a stored null. `$class` is typed as the Class or any subclass the Domain can
|
|
172
|
+
name. A Property whose name the SDK takes goes under `$prop` by its name: `id` on rows, a handle
|
|
173
|
+
member (`id`, `path`, `is`, `isExactly`, `via`) on handles, and an Edge's roles on an Edge read at
|
|
174
|
+
the root. A Property named `path` is `row.path` on a row and `a.$prop.path` on a handle. These
|
|
175
|
+
names are frozen, and no Property name starts with `$`, so a Property never moves. Two Properties of one name that two parent Classes declare, when the Class
|
|
176
|
+
declares none of its own, each go under `$` and their owner's name in lower camel case:
|
|
177
|
+
`row.$record.title`. The SDK's row keys (`$class`, `$edge`, `$source`, `$target`, `$withheld` and
|
|
178
|
+
`$prop`) are frozen too, and an owner group that would take one gets one more `$`: an owner named
|
|
179
|
+
`Class` groups under `$$class`.
|
|
180
|
+
|
|
181
|
+
An Edge read at the root answers rows of `{ $class, $source, $target }`, the Edge's Properties,
|
|
182
|
+
and both ends' rows under their roles. `edgeKey(row)` gives the `{ source, target, class }` a
|
|
183
|
+
Mutation or a guard names an Edge by. An Edge root's `get()`, `find()` and `exists()` take no id.
|
|
184
|
+
|
|
185
|
+
An undirected Edge's ends have no order: neither of its roles is kept at a fixed end. A condition
|
|
186
|
+
on its roles holds when one pairing of the Edge's two ends with its two roles meets the whole
|
|
187
|
+
condition, each end a Node its role accepts:
|
|
188
|
+
`d.involves.where((e) => e.person.id.eq(ada)).count({ upTo: 100 })` counts the Edges that involve
|
|
189
|
+
Ada, at either end. An undirected Edge root answers `exists()` and `count()` under any condition.
|
|
190
|
+
It lists rows only when its two roles accept the same Nodes and its condition reads neither role;
|
|
191
|
+
any other list of it, and an order key on a role's Property, throws a `TypeError`. Read those
|
|
192
|
+
Edges from a Node with `.via()`.
|
|
193
|
+
|
|
194
|
+
From a Node, a direction along an undirected Edge names a role, never a stored end:
|
|
195
|
+
`{ direction: 'outgoing' }` reads the Edges where the Node takes the first declared role and
|
|
196
|
+
answers the Nodes that take the second, `'incoming'` the reverse, and `'incident'` every Node at
|
|
197
|
+
the other end. A named relation reads its roles the same way. A relation throws a `TypeError`
|
|
198
|
+
when the role its direction names does not accept every Class it is read from, or when it reads
|
|
199
|
+
several Edge Classes and one of them can reach Nodes its far role does not accept: read that Edge
|
|
200
|
+
Class with its own `.via()`.
|
|
201
|
+
|
|
202
|
+
## Defining a Query
|
|
203
|
+
|
|
204
|
+
`defineQuery<Schema>()(id, { build, output?, errors? })` defines a Query. Its id is unique in the
|
|
205
|
+
Domain: dot-separated segments of lowercase letters, digits and `-`.
|
|
206
|
+
|
|
207
|
+
`build` returns one read, or a record of facets read together:
|
|
208
|
+
|
|
209
|
+
```ts
|
|
210
|
+
build: (account: NodeId, d) => ({
|
|
211
|
+
account: d.Account.get(account),
|
|
212
|
+
invoices: d.Invoice.where((i) => i.account.is(account)).all({ max: 500 }),
|
|
213
|
+
})
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
A facet may be a read, a list of reads (`items.map((item) => d.Item.get(item))`), or `undefined`
|
|
217
|
+
for a read the input makes optional.
|
|
218
|
+
|
|
219
|
+
Reads that wait for others are chained with `steps`, `build`'s third parameter.
|
|
220
|
+
`steps(first, (earlier) => next, …)` takes two to eight steps and reads them in order. The first
|
|
221
|
+
is a record of facets; each next one is a function of the merged results of the steps before it,
|
|
222
|
+
and returns a record of facets none of them read. A facet name read again does not compile, and
|
|
223
|
+
throws a `TypeError` before the step reads. A Query whose reads wait for none returns them
|
|
224
|
+
without `steps`. These steps order the reads of one call: they are not a Workflow's durable
|
|
225
|
+
Steps, and nothing of them is journaled or replayed.
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
build: (id: NodeId, { Article, Comment }, steps) =>
|
|
229
|
+
steps({ article: Article.find(id) }, ({ article }) => ({
|
|
230
|
+
comments:
|
|
231
|
+
article &&
|
|
232
|
+
Comment.where((c) => [
|
|
233
|
+
c.article.is(id),
|
|
234
|
+
article.publishedAt && c.postedAt.gte(article.publishedAt),
|
|
235
|
+
]).first(20),
|
|
236
|
+
})),
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
`output(results, input, { error, is })` maps the results to the Query's answer. It is
|
|
240
|
+
synchronous and pure, and returns portable JSON. Without it, the Query answers what `build` read.
|
|
241
|
+
`is(row, classKey)` narrows a row to a Class or its subclasses. An expected case is a union in the
|
|
242
|
+
output, not an error.
|
|
243
|
+
|
|
244
|
+
## Calling a Query
|
|
245
|
+
|
|
246
|
+
An Action calls `query(query, input, { as })`, where `as` is `executor` (the authority the handler
|
|
247
|
+
executes with) or `caller` (the incoming caller). An `auth: 'anonymous'` callable reads as
|
|
248
|
+
`executor` only. A Query with no input is called with `undefined`.
|
|
249
|
+
|
|
250
|
+
A page Query, whose single read is `.page({ max })`, takes the page size and the cursor at the
|
|
251
|
+
call and answers `{ rows, next? }`; its `output` keeps `rows` and `next`. `size` is a whole number
|
|
252
|
+
from 1 to `max`, `max` when omitted; any other value throws a `TypeError`:
|
|
253
|
+
|
|
254
|
+
```ts
|
|
255
|
+
const first = await query(articleTitles, undefined, { as: 'caller', size: 50 })
|
|
256
|
+
const second = first.next
|
|
257
|
+
? await query(articleTitles, undefined, { as: 'caller', size: 50, after: first.next })
|
|
258
|
+
: undefined
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
`query.all(query, input, { as, max })` reads every row of a page Query, page after page, and
|
|
262
|
+
answers the rows of its `output`; past `max` rows, it raises `TOO_MANY` as `all({ max })` does.
|
|
263
|
+
Each page is a read of its own, at its own snapshot and within its own bounds, and asks for no more
|
|
264
|
+
rows than `max` leaves, plus one:
|
|
265
|
+
|
|
266
|
+
```ts
|
|
267
|
+
const titles = await query.all(articleTitles, undefined, { as: 'caller', max: 5_000 })
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
A durable Workflow reads in a Step, as its executor:
|
|
271
|
+
`step.query('load-article', articleById, input.article, { as: 'executor' })`. The output is
|
|
272
|
+
journaled, and a replay returns it. A `QueryError` other than `REFUSED` fails the Step at once,
|
|
273
|
+
and a replay throws it again; so does the `TypeError` of an undeclared crossing (S12) a journal
|
|
274
|
+
holds. A Step reads as the Domain itself, which S12 does not check. A `REFUSED` read
|
|
275
|
+
is a failed attempt like any Kernel refusal: a permanent one exhausts the Step at once, and a
|
|
276
|
+
stale snapshot spends no attempt. An inline Workflow calls `query(query, input, { as })` from its
|
|
277
|
+
context, as an Action does, inside a named `step.run`.
|
|
278
|
+
|
|
279
|
+
## Errors
|
|
280
|
+
|
|
281
|
+
A read that cannot be answered raises `QueryError`, with the Query's id, a code and the details
|
|
282
|
+
of that code:
|
|
283
|
+
|
|
284
|
+
| Code | When | Details |
|
|
285
|
+
| --- | --- | --- |
|
|
286
|
+
| `NOT_FOUND` | A root `get` found nothing. | `class`; `target` when the read named one |
|
|
287
|
+
| `NOT_READABLE` | `get` or `find` met a fact the reader may not read. | `class`; `id`, a Node's id or an Edge's key |
|
|
288
|
+
| `INTEGRITY` | A relation's `get` found none, or a second row came where one is allowed. | `relation`; `parent` for a relation; `found: 0 \| 2` |
|
|
289
|
+
| `TOO_MANY` | Past a verb's `max` or `query.all`'s, a verb bound of 83,332, the Query's 100,000 rows or its 32 reads; or an answer past the bytes one response may carry. | `limit: 'max' \| 'rows' \| 'reads' \| 'bytes'`; `bound` |
|
|
290
|
+
| `REFUSED` | The Kernel refused the read. | `kernelCode`; `retryable`, whether a retry may succeed |
|
|
291
|
+
| `INPUT_INVALID` | The SDK or the Kernel refused the document the Query built, before reading anything. | `kernelCode`, `phase` and `path` when the Kernel names them; `limit: 'in'` for an `in` past 16 values |
|
|
292
|
+
| `OUTDATED` | The Host's Registry does not match the Domain's build. | `kernelCode: 'QUERY_EXPECTATION_MISMATCH'` |
|
|
293
|
+
| `UNSUPPORTED` | The Kernel does not serve Query v7, or its answer leaves out a row's Class. | `feature: 'v7' \| 'classes'` |
|
|
294
|
+
|
|
295
|
+
`isQueryError(error, code?)` recognizes one.
|
|
296
|
+
|
|
297
|
+
A `QueryError` an Action or an inline Workflow does not catch reaches its caller as follows:
|
|
298
|
+
|
|
299
|
+
- One the Kernel refused (`REFUSED`, `OUTDATED`, `UNSUPPORTED` for `v7`, `INPUT_INVALID` with a
|
|
300
|
+
`kernelCode`, `TOO_MANY` past the Host's bytes) reaches it as that refusal: the Kernel's public
|
|
301
|
+
code, message and data. A Kernel code outside the public codes reaches it as
|
|
302
|
+
`BACKEND_UNAVAILABLE`.
|
|
303
|
+
- One the SDK raised itself, the client's bytes included, reaches it as an internal error.
|
|
304
|
+
|
|
305
|
+
A refusal the caller handles by code is declared in `errors`, as on Actions, and raised by
|
|
306
|
+
`output`:
|
|
307
|
+
|
|
308
|
+
```ts
|
|
309
|
+
const articleNotFound = {
|
|
310
|
+
family: 'NOT_FOUND',
|
|
311
|
+
message: 'The article does not exist.',
|
|
312
|
+
details: z.strictObject({ article: z.string() }),
|
|
313
|
+
} as const
|
|
314
|
+
|
|
315
|
+
export const articleAuthor = defineQuery<typeof schema>()('publishing.article.author', {
|
|
316
|
+
build: (article: NodeId, d) => d.Article.with((a) => ({ author: a.author.find() })).find(article),
|
|
317
|
+
output: (row, article, { error }) => {
|
|
318
|
+
if (row === undefined) throw error('ARTICLE_NOT_FOUND', { article })
|
|
319
|
+
return row.author === undefined
|
|
320
|
+
? { kind: 'unassigned' as const }
|
|
321
|
+
: { kind: 'assigned' as const, author: row.author.id }
|
|
322
|
+
},
|
|
323
|
+
errors: { ARTICLE_NOT_FOUND: articleNotFound },
|
|
324
|
+
})
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
A Function lets a Query's error reach its own caller by declaring it again:
|
|
328
|
+
`{ errors: { ...articleAuthor.errors } }`.
|
|
329
|
+
|
|
330
|
+
## Bounds and checks
|
|
331
|
+
|
|
332
|
+
Before a step sends anything, the SDK checks:
|
|
333
|
+
|
|
334
|
+
- **Bounds (S11).** A Query makes at most 32 reads and reads at most 100,000 rows, counted from
|
|
335
|
+
its verbs' bounds and its relations per parent row. A verb's bound is at most 83,332. Past one,
|
|
336
|
+
the read raises `TOO_MANY`. An `in` takes at most 16 values; past them, it raises
|
|
337
|
+
`INPUT_INVALID`. Fewer than 2 or more than 8 steps do not compile, and `steps` throws a
|
|
338
|
+
`TypeError` when `build` calls it.
|
|
339
|
+
- **Requirements (S12).** A read `{ as: 'caller' }` answers only what both the caller and the
|
|
340
|
+
Domain may observe, and leaves out the rest without saying so. Of a Class of a direct
|
|
341
|
+
dependency whose read and traverse rules both admit only some callers, a relation that crosses
|
|
342
|
+
it needs the scope `read` or `traverse` on it in the Domain's requirements:
|
|
343
|
+
`requirements({ scopes: [{ on: Class, operations: ['traverse'] }] })`. Of one whose read rule
|
|
344
|
+
admits only some callers, a relation's condition that tests one of its values needs the scope
|
|
345
|
+
`read` on it: the Kernel drops what that test cannot decide. Otherwise the call throws a
|
|
346
|
+
`TypeError` naming the Query, the relation and the requirement to add. A rule that admits every
|
|
347
|
+
caller (`true`, or none) needs nothing. A requirement covers its own Class only, as the Kernel's
|
|
348
|
+
grants do; a Class a relation reaches stands for each concrete Class under it, itself when
|
|
349
|
+
concrete. Roots, Kernel Classes and the Domain's own Classes need nothing. A read
|
|
350
|
+
`{ as: 'executor' }` is the Domain's own, which no requirement changes: it is not checked. A
|
|
351
|
+
relation an empty list folds away is checked as if the list were not empty. A condition the
|
|
352
|
+
input leaves unbuilt, such as a falsy `where` entry or an `undefined` facet, is not checked.
|
|
353
|
+
|
|
354
|
+
`checkQuery(query, sampleInput, { domain, as? })` from `@astrale-os/sdk/testing` runs both
|
|
355
|
+
checks in a test, without a Kernel, on the first step it builds for its sample input. Give it an
|
|
356
|
+
input that builds every optional condition, and test later steps through a call. Given the
|
|
357
|
+
Domain's definition it checks S12 as a read for the caller is checked; `as: 'executor'` and the
|
|
358
|
+
Schema alone skip S12.
|
|
359
|
+
|
|
360
|
+
Neither check sees an answer's size. One answer is bounded in bytes, 16 MiB by default, by the Host
|
|
361
|
+
that sends it and by the Kernel client that receives it (`maximumResponseBytes`). Over HTTP, past
|
|
362
|
+
either bound, the read raises `TOO_MANY` with `limit: 'bytes'` and that bound, and the SDK does not
|
|
363
|
+
split it. A Host older than Kernel beta.34 names no bound when it refuses an answer: the read raises
|
|
364
|
+
`REFUSED` with `kernelCode: 'LIMIT_EXCEEDED'`. Over a WebSocket, a message past either bound closes
|
|
365
|
+
the connection instead, and the read fails as a network failure does. A read whose rows can be large
|
|
366
|
+
reads with `page` where its caller can, or keeps `max` at what that size allows.
|
|
367
|
+
|
|
368
|
+
The Domain linter also reads Queries:
|
|
369
|
+
|
|
370
|
+
- `QRY-CLOCK` refuses a clock read in `build` or `output`. Take now in the input.
|
|
371
|
+
- `QRY-ROWS` warns when a Query's constant bounds multiply past 10,000 rows.
|
|
372
|
+
- `QRY-FALSY` warns on a condition entry `x && p.eq(x)` or `x ? p.eq(x) : undefined`
|
|
373
|
+
whose `x` may be `false` or `0`, wherever falsy entries are skipped. Write
|
|
374
|
+
`x !== undefined && p.eq(x)` to compare whenever `x` is set, or say that `false` or `0` means no
|
|
375
|
+
filter: `x ? p.eq(true) : undefined` for a flag, `x !== undefined && x !== 0 && p.gte(x)` for a
|
|
376
|
+
number.
|
|
377
|
+
|
|
378
|
+
## Beyond v7
|
|
379
|
+
|
|
380
|
+
What v7 cannot express is bridged inside the Query, with a step or in `output`. A bridge's bound
|
|
381
|
+
and steps count toward the Query's bounds, and its callers never see it. When the Kernel serves
|
|
382
|
+
the construct, the bridge moves into the read and the output type does not change. Beyond a long
|
|
383
|
+
root `id.in`, the SDK never splits a read behind its author.
|
|
384
|
+
|
|
385
|
+
| The business asks | Bridge inside the Query |
|
|
386
|
+
| --- | --- |
|
|
387
|
+
| A value compared with a parent's | A first step reads the parent and the next compares with its value; or read both and filter in `output`. |
|
|
388
|
+
| Two parts of a pattern meeting at one Node | Read both with `.with`, compare in `output`. |
|
|
389
|
+
| Ancestors, a sub-tree at any depth | One step per level reads the next with `id.in`, up to 8 steps. |
|
|
390
|
+
| Sums, averages, groups | Read the values with `all({ max })`, compute in `output`. |
|
|
391
|
+
| Case-insensitive search, locale sorting | A normalized Property the Domain writes, or filter and sort in `output`. |
|
|
392
|
+
| Several unrelated lists | Facets of one Query, each read at its own snapshot. |
|
|
393
|
+
|
|
394
|
+
A filter in `output` runs after the Kernel applied the verb's bound.
|
|
395
|
+
|
|
396
|
+
## Canonical documents
|
|
397
|
+
|
|
398
|
+
`d.document(query)` reads one canonical v7 document whose lists carry a `limit`. Its rows are typed
|
|
399
|
+
`unknown`, so `output` validates them:
|
|
400
|
+
|
|
401
|
+
```ts
|
|
402
|
+
import { z } from 'zod'
|
|
403
|
+
|
|
404
|
+
export const recentArticles = defineQuery<typeof schema>()('publishing.article.recent', {
|
|
405
|
+
build: (_: undefined, d) =>
|
|
406
|
+
d.document({
|
|
407
|
+
query: 'astrale.query/7',
|
|
408
|
+
list: { nodes: ['publishing.example:class.Article'], select: 'value', limit: 20 },
|
|
409
|
+
}),
|
|
410
|
+
output: (rows) => z.array(z.looseObject({ id: z.string() })).parse(rows),
|
|
411
|
+
})
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
## Defining a Mutation
|
|
415
|
+
|
|
416
|
+
A Mutation takes the same form, over the same handles:
|
|
417
|
+
`defineMutation<Schema>()(id, { build, output?, reject?, errors? })`. `build(input, d, mutation)`
|
|
418
|
+
is synchronous; each write names its Class by its handle, and a write names one Class:
|
|
419
|
+
|
|
420
|
+
```ts
|
|
421
|
+
// The Schema declares the key: no two Workspaces share a slug.
|
|
422
|
+
const Workspace = nodeClass({ properties: { slug: property(z.string()) }, unique: [['slug']], … })
|
|
423
|
+
|
|
424
|
+
export const createWorkspace = defineMutation<typeof schema>()('workspace.create', {
|
|
425
|
+
build: (input: { readonly slug: string }, { Workspace }, mutation) => {
|
|
426
|
+
mutation.createNode({ as: 'workspace', class: Workspace, props: { slug: input.slug } })
|
|
427
|
+
},
|
|
428
|
+
reject: (failure, input, { error }) => {
|
|
429
|
+
if (failure.code !== 'MUTATION_POST_STATE_INVALID' || failure.rule !== 'duplicate-key') {
|
|
430
|
+
throw failure
|
|
431
|
+
}
|
|
432
|
+
throw error('SLUG_TAKEN', { slug: input.slug })
|
|
433
|
+
},
|
|
434
|
+
errors: { SLUG_TAKEN: slugTaken },
|
|
435
|
+
})
|
|
436
|
+
|
|
437
|
+
await mutate(createWorkspace, { slug }, { as: 'caller' })
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
`output(result, input)` maps the committed `MutationResult`, which the Mutation answers without it.
|
|
441
|
+
`reject(failure, input, { error, is })` maps an expected refusal to the same output, or raises a
|
|
442
|
+
declared error: here the Kernel refuses a second Workspace with the slug, `duplicate-key`, on every
|
|
443
|
+
write that could make one, and the Mutation names that refusal. A defined Mutation's id shares
|
|
444
|
+
the Queries' namespace, and every call names its authority: `mutate(mutation, input, { as })`,
|
|
445
|
+
`step.mutate(id, mutation, input, { as: 'executor' })`. The closure form,
|
|
446
|
+
`defineMutation<Schema>()((domain) => ({ id, build, project? }))`, is deprecated.
|
|
447
|
+
|
|
448
|
+
## Guards
|
|
449
|
+
|
|
450
|
+
A Mutation guards its write on a range: a Class handle after `where`, `union` and `orderBy`, or a
|
|
451
|
+
canonical v7 Query. `mutation.expect.none(range)`, `expect.exists(range)`,
|
|
452
|
+
`expect.count(range, n | { atLeast?, atMost? })` or `expect.unchanged(range, ids)`. The Kernel
|
|
453
|
+
decides the guard with the Mutation, on the range's Classes and `where`, and for `unchanged` its
|
|
454
|
+
`orderBy`. A read (`first`, `exists`, `count`…) and a rendered set (`with`, `ref`) are refused:
|
|
455
|
+
their verb, size or rendering would not reach the guard. Each verb takes `{ name }` last, and a
|
|
456
|
+
refusal carries the failed precondition's name as `failure.precondition`.
|
|
457
|
+
|
|
458
|
+
A guard states what the Schema cannot: a condition across Nodes at commit, a count that no
|
|
459
|
+
cardinality states (at most 100 Tasks in a Project), an unchanged list. What the Schema declares is
|
|
460
|
+
never a guard: a key (`unique`), a cardinality, the endpoints an Edge accepts, a state machine's
|
|
461
|
+
transitions. The Kernel checks those on every write, where a guard costs a read and holds only for
|
|
462
|
+
the Mutations that carry it. Closing a Project is its state machine's transition; that none of its
|
|
463
|
+
Tasks is open is a guard:
|
|
464
|
+
|
|
465
|
+
```ts
|
|
466
|
+
export const closeProject = defineMutation<typeof schema>()('project.close', {
|
|
467
|
+
build: (input: { readonly project: NodeId }, { Project, Task }, mutation) => {
|
|
468
|
+
mutation.expect.none(
|
|
469
|
+
Task.where((t) => [t.project.is(input.project), t.status.eq('open')]),
|
|
470
|
+
{ name: 'open-tasks' },
|
|
471
|
+
)
|
|
472
|
+
mutation.transition({
|
|
473
|
+
node: input.project,
|
|
474
|
+
class: Project,
|
|
475
|
+
property: 'status',
|
|
476
|
+
from: 'open',
|
|
477
|
+
event: 'close',
|
|
478
|
+
})
|
|
479
|
+
},
|
|
480
|
+
reject: (failure, input, { error }) => {
|
|
481
|
+
if (failure.code !== 'MUTATION_PRECONDITION_FAILED' || failure.precondition !== 'open-tasks') {
|
|
482
|
+
throw failure
|
|
483
|
+
}
|
|
484
|
+
throw error('OPEN_TASKS', { project: input.project })
|
|
485
|
+
},
|
|
486
|
+
errors: { OPEN_TASKS: openTasks },
|
|
487
|
+
})
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
## Query V6
|
|
491
|
+
|
|
492
|
+
Query V6 definitions keep their meaning and are deprecated. See
|
|
493
|
+
[Query V6 and the move to v7](legacy/query-v6.md).
|
package/docs/release.md
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# SDK release lifecycle
|
|
2
|
+
|
|
3
|
+
Release Please owns the versions and GitHub releases for the SDK package set:
|
|
4
|
+
|
|
5
|
+
- `@astrale-os/sdk`
|
|
6
|
+
- `@astrale-os/adapter-cloudflare`
|
|
7
|
+
- `@astrale-os/adapter-astrale`
|
|
8
|
+
- `create-astrale-domain`
|
|
9
|
+
|
|
10
|
+
The Node workspace plugin follows local dependency edges. Every internal release edge uses
|
|
11
|
+
`workspace:*`, so a changed SDK refreshes the dependent adapter and scaffolder packages in the same
|
|
12
|
+
Release Please pull request and publication rewrites each edge to that dependency's exact version.
|
|
13
|
+
Never use a caret or tilde for an internal release edge: an immutable adapter must not resolve a
|
|
14
|
+
newer SDK or adapter after publication. The shared publisher consumes those versions; it never
|
|
15
|
+
invents a release version.
|
|
16
|
+
|
|
17
|
+
Dependency installation, authoritative publication, and public qualification are npmjs-only. npm
|
|
18
|
+
publication uses OIDC Trusted Publishing. After that proof completes, the workflow mirrors the exact
|
|
19
|
+
SDK and adapter tarballs to private GitHub Packages copies. GitHub Packages is never a consumer,
|
|
20
|
+
build, installation, or qualification source. Never add a PAT, an npm token, an auth file, or a
|
|
21
|
+
repository package token; no credential may enter a tracked file, lockfile, package archive, or build
|
|
22
|
+
log.
|
|
23
|
+
|
|
24
|
+
## Normal beta release
|
|
25
|
+
|
|
26
|
+
Prerequisite: every exact Kernel dependency in the SDK manifest is already published on npm and the
|
|
27
|
+
SDK passes typecheck, test, build, pack, and fresh-consumer gates against those artifacts. Never use
|
|
28
|
+
a local checkout, tarball, or override to make the release build pass.
|
|
29
|
+
|
|
30
|
+
1. Merge conventional feature and fix pull requests into `main`.
|
|
31
|
+
The squash-merge title is Release Please input: use `feat` for a public capability or API change
|
|
32
|
+
and `fix` for a behavioral defect. Never classify a publication-bearing change as `refactor`,
|
|
33
|
+
`docs`, `chore`, or `test`; those types do not advance the beta
|
|
34
|
+
package cohort.
|
|
35
|
+
2. The `Release` workflow creates or refreshes the single Release Please pull request.
|
|
36
|
+
3. Select **Approve workflows to run** for that bot-authored pull request and wait for every required
|
|
37
|
+
check. GitHub can mark these workflows `action_required`; this is an approval gate, not a passed
|
|
38
|
+
run.
|
|
39
|
+
4. Review every changed package version, exact internal dependency, changelog, and
|
|
40
|
+
`.release-please-manifest.json` entry.
|
|
41
|
+
5. Merge the Release Please pull request.
|
|
42
|
+
6. Release Please creates an immutable GitHub prerelease for every released component. Only then does
|
|
43
|
+
`Release` dispatch the standalone `Publish` workflow with the exact released commit SHA, preserving
|
|
44
|
+
its npm Trusted Publishing identity. Publish rejects a non-SHA or a checkout mismatch before npm I/O.
|
|
45
|
+
7. The shared package publisher builds the workspace and publishes every public package to npm. A
|
|
46
|
+
`-beta.N` version advances npm `beta`; npm `latest` remains on the last stable version.
|
|
47
|
+
8. The same workflow then runs `pnpm run qualify:publications` without a token. This creates isolated
|
|
48
|
+
temporary stores, installs the four exact manifest versions from npmjs, generates a Domain with
|
|
49
|
+
`linkWorkspacePackages: false`, pins that generated project to the exact SDK and adapter versions,
|
|
50
|
+
and runs its typecheck, tests, build, and package command. Any missing publication, transitive
|
|
51
|
+
dependency, wrong version, non-exact internal cohort edge, local source, override, or GitHub
|
|
52
|
+
registry reference fails the workflow.
|
|
53
|
+
9. A separate least-privilege job downloads the exact SDK and adapter tarballs from npm, verifies
|
|
54
|
+
their npm SHA-512 integrity, mirrors them with `GITHUB_TOKEN`, and then requires byte-identical
|
|
55
|
+
GitHub downloads, matching release-channel tags, private visibility, and an exact link to
|
|
56
|
+
`astrale-os/sdk`. The scaffolder remains npm-only.
|
|
57
|
+
|
|
58
|
+
The publisher receives package directories in strict producer order: SDK, Cloudflare adapter,
|
|
59
|
+
Astrale adapter, then scaffolder. The shared action validates this dependency order and completes npm
|
|
60
|
+
plus the exact release-channel dist-tag for one package before it starts the next. A linked workspace
|
|
61
|
+
build is therefore never treated as publication proof.
|
|
62
|
+
|
|
63
|
+
npm publication has no token fallback. All four npm packages must configure GitHub Actions Trusted
|
|
64
|
+
Publishing for this repository and the `publish.yml` workflow. A missing Trusted Publisher or a wrong
|
|
65
|
+
dist-tag is an explicit, fail-closed publication error; do not work around it with a PAT or npm token.
|
|
66
|
+
|
|
67
|
+
The mirror job starts only after the anonymous npm qualification succeeds. It has `packages: write`
|
|
68
|
+
but no npm OIDC permission, performs no build or workspace install, and cannot publish to npm. A
|
|
69
|
+
mirror failure makes `Publish` red without undoing the already-complete npm release. Rerunning the
|
|
70
|
+
failed job is safe: existing versions must be byte-identical, no version is overwritten or deleted,
|
|
71
|
+
and tags are reconciled only when npm still points them at that exact version. Do not backfill older
|
|
72
|
+
version gaps during initial rollout; the next ordinary beta release is the admission proof.
|
|
73
|
+
|
|
74
|
+
Ordinary source pushes do not publish. Do not manually edit package versions, manually dispatch
|
|
75
|
+
`Publish`, or push release tags during the normal flow.
|
|
76
|
+
|
|
77
|
+
## Start the new Auth beta series
|
|
78
|
+
|
|
79
|
+
The session-owned Auth API starts a new SDK beta series at `0.6.0-beta.0`. Its feature PR sets
|
|
80
|
+
only the SDK's package-local `release-as` to that version. Release Please owns the actual manifest
|
|
81
|
+
and cohort bumps. Remove that one-shot override from the generated release PR before merging it.
|
|
82
|
+
This keeps the release on npm `beta`, while existing SDK `0.5.0` prerelease ranges retain the old API.
|
|
83
|
+
|
|
84
|
+
## Promote the package set to stable
|
|
85
|
+
|
|
86
|
+
Create one promotion pull request that removes only these beta settings from
|
|
87
|
+
`.release-please-config.json`:
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
"versioning": "prerelease",
|
|
91
|
+
"prerelease": true,
|
|
92
|
+
"prerelease-type": "beta"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Keep the Node workspace plugin, `always-update`, package map, and workflows unchanged. In the same
|
|
96
|
+
promotion pull request, temporarily add these package-local overrides:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
"packages": {
|
|
100
|
+
".": { "component": "sdk", "release-as": "0.6.0" },
|
|
101
|
+
"adapter-cloudflare": { "component": "adapter-cloudflare", "release-as": "0.5.0" },
|
|
102
|
+
"adapter-astrale": { "component": "adapter-astrale", "release-as": "0.5.0" },
|
|
103
|
+
"create-astrale-domain": {
|
|
104
|
+
"component": "create-astrale-domain",
|
|
105
|
+
"release-as": "0.3.0"
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
After that promotion pull request lands, Release Please proposes those stable versions. Remove all
|
|
111
|
+
four `release-as` properties from the generated stable release pull request, rerun its checks, and
|
|
112
|
+
merge it. This publishes npm `latest` and ordinary GitHub releases. The npm `beta` tags intentionally
|
|
113
|
+
remain on the last beta and do not affect bare installs.
|
|
114
|
+
|
|
115
|
+
## Verification
|
|
116
|
+
|
|
117
|
+
Always name npmjs explicitly when inspecting releases so the verification also proves the public
|
|
118
|
+
registry boundary.
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
gh run list --repo astrale-os/sdk --workflow Release --limit 5
|
|
122
|
+
gh run list --repo astrale-os/sdk --workflow Publish --limit 5
|
|
123
|
+
npm view @astrale-os/sdk dist-tags --json --registry=https://registry.npmjs.org
|
|
124
|
+
npm view @astrale-os/adapter-cloudflare dist-tags --json --registry=https://registry.npmjs.org
|
|
125
|
+
npm view @astrale-os/adapter-astrale dist-tags --json --registry=https://registry.npmjs.org
|
|
126
|
+
npm view create-astrale-domain dist-tags --json --registry=https://registry.npmjs.org
|
|
127
|
+
gh api orgs/astrale-os/packages/npm/sdk --jq '{visibility,repository:.repository.full_name}'
|
|
128
|
+
gh api orgs/astrale-os/packages/npm/adapter-cloudflare --jq '{visibility,repository:.repository.full_name}'
|
|
129
|
+
gh api orgs/astrale-os/packages/npm/adapter-astrale --jq '{visibility,repository:.repository.full_name}'
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The SDK, adapters, scaffolder, generated manifest, and every transitive runtime dependency must be
|
|
133
|
+
installable from npmjs without authentication. Prove that boundary from a clean temporary directory:
|
|
134
|
+
|
|
135
|
+
```ini
|
|
136
|
+
# ./npmrc (in the smoke-test parent directory)
|
|
137
|
+
registry=https://registry.npmjs.org/
|
|
138
|
+
always-auth=false
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Then run the complete smoke test:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
NPM_CONFIG_USERCONFIG="$PWD/npmrc" npm install @astrale-os/sdk@beta
|
|
145
|
+
NPM_CONFIG_USERCONFIG="$PWD/npmrc" npx -y create-astrale-domain@beta beta-smoke --yes
|
|
146
|
+
cd beta-smoke
|
|
147
|
+
NPM_CONFIG_USERCONFIG="../npmrc" pnpm install --no-frozen-lockfile
|
|
148
|
+
pnpm typecheck
|
|
149
|
+
pnpm test
|
|
150
|
+
pnpm build
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Inspect the generated lockfile and installed package manifests. They must resolve the released SDK and
|
|
154
|
+
adapter package set and the SDK-owned public Kernel dependencies from npmjs, not `latest`, GitHub
|
|
155
|
+
Packages, workspace links, Git URLs, or an older manually published beta.
|