@softr/sdk 0.0.27 → 0.0.29

package/dist/action.d.ts

@@ -31,84 +31,41 @@ type ActionPermission = {
  */
 interface SoftrDatasources {}
 type SoftrDatasourceId = keyof SoftrDatasources extends never ? string : keyof SoftrDatasources & string;
-/** The read type one datasource returns. */
 type ReadOf<TDatasource$1> = TDatasource$1 extends keyof SoftrDatasources ? SoftrDatasources[TDatasource$1] extends {
   read: infer TRecord;
 } ? TRecord : never : never;
-/**
- * The DSv2 type name one field declares, as codegen emitted it: `"NUMBER"`, `"SELECT[]"`.
- * `never` for a field no augmentation describes.
- */
 type FieldTypeOf<TDatasource$1, TFieldId> = TDatasource$1 extends keyof SoftrDatasources ? SoftrDatasources[TDatasource$1] extends {
   fieldTypes: infer TTypes;
 } ? TFieldId extends keyof TTypes ? TTypes[TFieldId] : never : never : never;
-/** The write type one datasource accepts for one operation. */
 type WriteOf<TDatasource$1, TOperation$1> = TDatasource$1 extends keyof SoftrDatasources ? TOperation$1 extends keyof SoftrDatasources[TDatasource$1] ? SoftrDatasources[TDatasource$1][TOperation$1] : never : never;
-/** The field ids a write may name. Any string, until {@link SoftrDatasources} is declared. */
 type FieldIdOf<TDatasource$1, TOperation$1> = keyof SoftrDatasources extends never ? string : keyof WriteOf<TDatasource$1, TOperation$1> & string;
-/**
- * The field ids a read may name. Any string, until {@link SoftrDatasources} is declared.
- *
- * A read constrains against the record type rather than a write type, because a read may
- * name a field no write can: a formula or a lookup is on the record and on neither.
- */
 type ReadFieldIdOf<TDatasource$1> = keyof SoftrDatasources extends never ? string : keyof ReadOf<TDatasource$1> & string;
-/**
- * What an action declares, as the type layer reads it. `permission` is absent because no
- * call site depends on it, and the build reads it off the value.
- */
 type ActionShape = {
   id: string;
   datasource: SoftrDatasourceId;
   operation: ActionOperation;
   fields?: Record<string, string>;
 };
-/** What a read declares. A read is the whole field list, so `fields` is not optional. */
 type ReadShape = ActionShape & {
   operation: "read";
   fields: Record<string, string>;
 };
-/**
- * What one action writes: its own aliases, each resolved to the value that field accepts.
- *
- * An alias renames the field, and a mapped type keeps a property's docstring only while it
- * keeps the key, so the prose that sits on the field in `softr-env.d.ts` does not reach the
- * call site. The type does.
- */
 type ActionData<TShape extends ActionShape> = keyof SoftrDatasources extends never ? Record<string, unknown> : TShape extends {
   datasource: infer TDatasource;
   operation: infer TOperation;
   fields: infer TFields;
 } ? { [Alias in keyof TFields]?: WriteOf<TDatasource, TOperation>[TFields[Alias] & keyof WriteOf<TDatasource, TOperation>] } : Record<string, unknown>;
-/**
- * What a mutation reads back: the same aliases, resolved against the table's read type.
- *
- * A write returns the record it wrote, and the SDK aliases its fields on the way out, so a
- * field the action never declared is absent from the result as well as from the payload.
- *
- * Every alias the action does declare is present. An empty field reads as `null`, so nothing
- * here is optional.
- */
 type ActionRecord<TShape extends ActionShape> = keyof SoftrDatasources extends never ? Record<string, unknown> : TShape extends {
   datasource: infer TDatasource;
   fields: infer TFields;
 } ? { [Alias in keyof TFields]: ReadOf<TDatasource>[TFields[Alias] & keyof ReadOf<TDatasource>] } : Record<string, unknown>;
 declare const brand: unique symbol;
-/**
- * A handle to a declared action, and the only thing a mutation accepts. The brand keeps it
- * nominal, so an object literal of the same shape will not do and no mutation can be reached
- * without passing through a declaration the build reads.
- *
- * The brand carries the declaration itself, which is what lets a call site resolve what the
- * action writes without codegen having said anything about this action.
- */
 type Action<TShape extends ActionShape = ActionShape> = {
   type: "action";
   id: TShape["id"];
 } & {
   readonly [brand]: TShape;
 };
-/** What a write action declares. */
 type WriteDeclaration<TId extends string, TDatasource$1, TOperation$1, TFields$1> = {
   id: TId;
   datasource: TDatasource$1;
@@ -116,15 +73,12 @@ type WriteDeclaration<TId extends string, TDatasource$1, TOperation$1, TFields$1
   fields: TFields$1;
   permission: ActionPermission;
 };
-/** What a read action declares. */
 type ReadDeclaration<TId extends string, TDatasource$1, TFields$1> = {
   id: TId;
   datasource: TDatasource$1;
-  operation: "read";
   fields: TFields$1;
   permission: ActionPermission;
 };
-/** What a delete action declares. `fields?: never` so a stray one is rejected rather than ignored. */
 type DeleteDeclaration<TId extends string, TDatasource$1> = {
   id: TId;
   datasource: TDatasource$1;
@@ -132,28 +86,15 @@ type DeleteDeclaration<TId extends string, TDatasource$1> = {
   fields?: never;
   permission: ActionPermission;
 };
-/** The whole declaration, which is what an action is at runtime and in the manifest. */
-
 /**
- * Declares a data operation: which datasource, which of the four operations, which fields
- * participate, and who may run it.
- *
- * One call per action, at module scope, with a literal: the build reads these declarations
- * to publish what the app may read and write.
+ * Declares a read: which datasource, which fields participate, and who may run it.
  *
- * The keys of `fields` are aliases the app chooses and the values are field ids of the
- * datasource the action names. The result, `data`, `where` and `orderBy` at the call site
- * are all keyed by those aliases, so nothing there restates what the action already says.
- *
- * A read fixes the table and the columns. It does not fix which rows: `where`, `orderBy` and
- * the paging arguments stay at the call site, because a list screen changes them as the user
- * types and a declaration cannot follow that.
+ * The argument must be a static object.
  *
  * @example
- * const publishedPosts = defineAction({
+ * const publishedPosts = defineQuery({
  *   id: "publishedPosts",
  *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
- *   operation: "read",
  *   fields: { title: "V1StGXR8", author: "Z7pQm4Kd", publishedAt: "Xp2dLh6v" },
  *   permission: { userGroup: "ALL_USERS" },
  * })
@@ -162,9 +103,21 @@ type DeleteDeclaration<TId extends string, TDatasource$1> = {
  *   .list(publishedPosts)
  *   .where((q) => q.publishedAt.lte(today))
  *   .orderBy((q) => q.publishedAt.desc)
+ */
+declare function defineQuery<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TFields$1 extends Record<string, ReadFieldIdOf<TDatasource$1>>>(definition: ReadDeclaration<TId, TDatasource$1, TFields$1>): Action<{
+  id: TId;
+  datasource: TDatasource$1;
+  operation: "read";
+  fields: TFields$1;
+}>;
+/**
+ * Declares a write: which datasource, whether it creates, updates or deletes, which fields
+ * participate, and who may run it.
+ *
+ * The argument must be a static object.
  *
  * @example
- * const closeOrderAction = defineAction({
+ * const closeOrder = defineMutation({
  *   id: "closeOrder",
  *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
  *   operation: "update",
@@ -172,24 +125,28 @@ type DeleteDeclaration<TId extends string, TDatasource$1> = {
  *   permission: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
  * })
  *
- * await ds.update(closeOrderAction, { id, data: { status: "closed" } })
+ * await ds.update(closeOrder, { id, data: { status: "closed" } })
+ *
+ * @example
+ * const removeOrder = defineMutation({
+ *   id: "removeOrder",
+ *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ *   operation: "delete",
+ *   permission: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
+ * })
+ *
+ * await ds.delete(removeOrder, { id })
  */
-declare function defineAction<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TFields$1 extends Record<string, ReadFieldIdOf<TDatasource$1>>>(definition: ReadDeclaration<TId, TDatasource$1, TFields$1>): Action<{
-  id: TId;
-  datasource: TDatasource$1;
-  operation: "read";
-  fields: TFields$1;
-}>;
-declare function defineAction<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TOperation$1 extends "create" | "update", const TFields$1 extends Record<string, FieldIdOf<TDatasource$1, TOperation$1>>>(definition: WriteDeclaration<TId, TDatasource$1, TOperation$1, TFields$1>): Action<{
+declare function defineMutation<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TOperation$1 extends "create" | "update", const TFields$1 extends Record<string, FieldIdOf<TDatasource$1, TOperation$1>>>(definition: WriteDeclaration<TId, TDatasource$1, TOperation$1, TFields$1>): Action<{
   id: TId;
   datasource: TDatasource$1;
   operation: TOperation$1;
   fields: TFields$1;
 }>;
-declare function defineAction<const TId extends string, const TDatasource$1 extends SoftrDatasourceId>(definition: DeleteDeclaration<TId, TDatasource$1>): Action<{
+declare function defineMutation<const TId extends string, const TDatasource$1 extends SoftrDatasourceId>(definition: DeleteDeclaration<TId, TDatasource$1>): Action<{
   id: TId;
   datasource: TDatasource$1;
   operation: "delete";
 }>;
 //#endregion
-export { Action, ActionData, ActionRecord, ActionShape, FieldTypeOf, ReadOf, ReadShape, SoftrDatasources, defineAction };
+export { Action, ActionData, ActionRecord, ActionShape, FieldTypeOf, ReadOf, ReadShape, SoftrDatasources, defineMutation, defineQuery };

package/dist/action.js

@@ -1,16 +1,17 @@
 //#region src/action.ts
-function defineAction(definition) {
+function defineQuery(definition) {
+	return {
+		type: "action",
+		...definition,
+		operation: "read"
+	};
+}
+function defineMutation(definition) {
 	return {
 		type: "action",
 		...definition
 	};
 }
-/**
-* True for anything {@link defineAction} produced, whatever its operation.
-*
-* Matched on `type` rather than with `instanceof`, so two copies of the SDK in one
-* dependency tree still recognise each other's actions.
-*/
 function isAction(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const candidate = value;
@@ -18,4 +19,4 @@ function isAction(value) {
 }
 
 //#endregion
-export { defineAction, isAction };
+export { defineMutation, defineQuery, isAction };