@softr/sdk 0.0.25 → 0.0.26-alpha-0

package/dist/action.d.ts

@@ -0,0 +1,195 @@
+import { SoftrUserGroupId } from "./auth/user.js";
+
+//#region src/action.d.ts
+type ActionOperation = "read" | "create" | "update" | "delete";
+type ActionPermission = {
+  userGroup: "ALL_USERS";
+} | {
+  userGroup: "NON_LOGGED_IN_USERS";
+} | {
+  userGroup: "LOGGED_IN_USERS";
+  userGroupIds?: Array<SoftrUserGroupId>;
+};
+/**
+ * Describes the datasources available in the app and their read, create and update types.
+ *
+ * This lets datasource IDs and fields in actions be type-checked.
+ *
+ * @example
+ * declare module "@softr/sdk" {
+ *   interface SoftrDatasources {
+ *     FrkQIVpeTtfJDT: {
+ *       name: "Cafes"
+ *       primaryField: "9QrOA"
+ *       read: CafesRead
+ *       create: CafesCreate
+ *       update: CafesUpdate
+ *       fieldTypes: { "9QrOA": "SINGLE_LINE_TEXT"; "1G3aA": "DATETIME" }
+ *     }
+ *   }
+ * }
+ */
+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;
+  operation: TOperation$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;
+  operation: "delete";
+  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.
+ *
+ * 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.
+ *
+ * @example
+ * const publishedPosts = defineAction({
+ *   id: "publishedPosts",
+ *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ *   operation: "read",
+ *   fields: { title: "V1StGXR8", author: "Z7pQm4Kd", publishedAt: "Xp2dLh6v" },
+ *   permission: { userGroup: "ALL_USERS" },
+ * })
+ *
+ * const { records } = await ds
+ *   .list(publishedPosts)
+ *   .where((q) => q.publishedAt.lte(today))
+ *   .orderBy((q) => q.publishedAt.desc)
+ *
+ * @example
+ * const closeOrderAction = defineAction({
+ *   id: "closeOrder",
+ *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ *   operation: "update",
+ *   fields: { status: "V1StGXR8", closedAt: "Z7pQm4Kd" },
+ *   permission: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
+ * })
+ *
+ * await ds.update(closeOrderAction, { id, data: { status: "closed" } })
+ */
+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<{
+  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<{
+  id: TId;
+  datasource: TDatasource$1;
+  operation: "delete";
+}>;
+//#endregion
+export { Action, ActionData, ActionRecord, ActionShape, FieldTypeOf, ReadOf, ReadShape, SoftrDatasources, defineAction };

package/dist/action.js

@@ -0,0 +1,21 @@
+//#region src/action.ts
+function defineAction(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;
+	return candidate.type === "action" && typeof candidate.id === "string" && typeof candidate.datasource === "string";
+}
+
+//#endregion
+export { defineAction, isAction };

package/dist/auth/isomorphic.d.ts

@@ -1,6 +1,5 @@
 import { User } from "./user.js";
-import { DatasourcePermissions } from "../types.js";
-import { Permissions } from "./permissions.js";
+import { DatasourcePermissions, Permissions } from "./permissions.js";
 import { Session, SoftrContext } from "./context.js";
 import * as _tanstack_react_start0 from "@tanstack/react-start";
 

package/dist/auth/permissions.d.ts

@@ -1,4 +1,3 @@
-import { DatasourcePermissions } from "../types.js";
 import { z } from "zod";
 
 //#region src/auth/permissions.d.ts
@@ -9,9 +8,15 @@ import { z } from "zod";
  * Rendering hints, not enforcement: every data request is authorized again
  * server-side, and these may go stale between the two.
  */
+type DatasourcePermissions = {
+  read: boolean;
+  create: boolean;
+  update: boolean;
+  delete: boolean;
+};
 type Permissions = {
   /** Keyed by datasource id. */
   datasources: Record<string, DatasourcePermissions>;
 };
 //#endregion
-export { Permissions };
+export { DatasourcePermissions, Permissions };

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { version } from "./package.js";
+import { fetchSoftrEnvInput, metadataSourceFromEnv } from "./codegen/fetch-metadata.js";
+import { renderSoftrEnv } from "./codegen/softr-env.js";
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+
+//#region src/cli.ts
+const OUTPUT = "softr-env.d.ts";
+async function generate() {
+	writeFileSync(path.resolve(process.cwd(), OUTPUT), renderSoftrEnv(await fetchSoftrEnvInput(metadataSourceFromEnv()), version), "utf8");
+	console.log(`[softr] wrote ${OUTPUT}`);
+}
+const [command] = process.argv.slice(2);
+if (command === "generate") await generate();
+else {
+	console.error(command ? `softr-sdk: unknown command '${command}'` : "softr-sdk: no command given");
+	console.error("usage: softr-sdk generate");
+	process.exit(1);
+}
+
+//#endregion
+export {  };