@hexclave/shared 1.0.3 → 1.0.5

package/src/config-authoring.test.ts

@@ -0,0 +1,52 @@
+import { expect, it } from "vitest";
+import { typeAssertExtends } from "./utils/types";
+import { defineStackConfig, type StackConfig } from "./config-authoring";
+
+const validConfig = defineStackConfig({
+  payments: {
+    items: {
+      todos: {
+        displayName: "Todo Slots",
+        customerType: "user",
+      },
+    },
+  },
+});
+const showOnboardingConfig = defineStackConfig("show-onboarding");
+
+typeAssertExtends<typeof validConfig, StackConfig>()();
+typeAssertExtends<typeof showOnboardingConfig, StackConfig>()();
+
+it("returns its input unchanged", () => {
+  expect(defineStackConfig(validConfig)).toBe(validConfig);
+  expect(defineStackConfig(showOnboardingConfig)).toBe(showOnboardingConfig);
+});
+
+defineStackConfig({
+  // @ts-expect-error Top-level dot notation should not be accepted in typed config files.
+  "payments.items": {
+    todos: {
+      displayName: "Todo Slots",
+      customerType: "user",
+    },
+  },
+});
+
+defineStackConfig({
+  payments: {
+    // @ts-expect-error Unknown keys should not be accepted in typed config files.
+    missingField: true,
+  },
+});
+
+defineStackConfig({
+  payments: {
+    items: {
+      todos: {
+        displayName: "Todo Slots",
+        // @ts-expect-error Invalid enum values should fail type-checking.
+        customerType: "workspace",
+      },
+    },
+  },
+});

package/src/config-authoring.ts

@@ -0,0 +1,37 @@
+import type { BranchConfigNormalizedOverride } from "./config/schema";
+
+type StackConfigObject = BranchConfigNormalizedOverride;
+export const showOnboardingHexclaveConfigValue = "show-onboarding";
+/** @deprecated Use `HexclaveConfig` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */
+export type StackConfig = StackConfigObject | typeof showOnboardingHexclaveConfigValue;
+
+// Hexclave alias — same shape, declared separately so it doesn't inherit the deprecation tag.
+export type HexclaveConfig = StackConfigObject | typeof showOnboardingHexclaveConfigValue;
+
+type StrictConfigShape<Actual, Expected> =
+  Expected extends readonly unknown[]
+    ? Actual extends readonly unknown[]
+      ? { [K in keyof Actual]: K extends keyof Expected ? StrictConfigShape<Actual[K], Expected[K]> : never }
+      : Actual
+    : Expected extends object
+      ? Actual extends object
+        ? Exclude<keyof Actual, keyof Expected> extends never
+          ? { [K in keyof Actual]: K extends keyof Expected ? StrictConfigShape<Actual[K], Expected[K]> : never }
+          : never
+        : Actual
+      : Actual;
+
+type StrictStackConfig<T extends StackConfig> =
+  T extends StackConfigObject
+    ? T & StrictConfigShape<T, StackConfigObject>
+    : T;
+
+/** @deprecated Use `defineHexclaveConfig` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */
+export function defineStackConfig<const T extends StackConfig>(config: StrictStackConfig<T>): T {
+  return config;
+}
+
+// Hexclave alias — separate function so it does not inherit the deprecation tag.
+export function defineHexclaveConfig<const T extends HexclaveConfig>(config: StrictStackConfig<T>): T {
+  return config;
+}

package/src/config-rendering.ts

@@ -0,0 +1,142 @@
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import { parseHexclaveConfigFileContent, renderConfigFileContent } from "./hexclave-config-file";
+export { parseHexclaveConfigFileContent, renderConfigFileContent };
+
+/**
+ * Packages that export the `HexclaveConfig` type, in priority order.
+ * The first match found in a project's dependencies wins. Hexclave-branded
+ * packages come first (canonical); the legacy `@stackframe/*` names remain
+ * so projects pinned to the last legacy release still render a config file
+ * that compiles against their installed SDK.
+ */
+const CONFIG_IMPORT_PACKAGES = [
+  "@hexclave/next",
+  "@hexclave/react",
+  "@hexclave/js",
+  "@hexclave/template",
+  "@stackframe/stack",
+  "@stackframe/react",
+  "@stackframe/js",
+  "@stackframe/template",
+] as const;
+
+/**
+ * Given a list of dependency names (from package.json), returns the SDK
+ * package that should be used for the `HexclaveConfig` import, or `undefined`
+ * if none of the known packages are installed.
+ */
+export function detectConfigImportPackage(dependencies: string[]): string | undefined {
+  for (const pkg of CONFIG_IMPORT_PACKAGES) {
+    if (dependencies.includes(pkg)) {
+      return pkg;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Walks up from `dir` to find the nearest `package.json` and returns the
+ * best SDK package to use for the `HexclaveConfig` type import.
+ */
+export function detectImportPackageFromDir(dir: string): string | undefined {
+  let current = dir;
+  while (true) {
+    const pkgPath = path.join(current, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        const deps = [
+          ...Object.keys(pkg.dependencies ?? {}),
+          ...Object.keys(pkg.devDependencies ?? {}),
+        ];
+        return detectConfigImportPackage(deps);
+      } catch {
+        return undefined;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return undefined;
+}
+
+import.meta.vitest?.test("renderConfigFileContent normalizes config exports", ({ expect }) => {
+  expect(renderConfigFileContent({
+    "payments.items.todos.displayName": "Todo Slots",
+    "payments.items.todos.customerType": "user",
+  })).toContain(`export const config: HexclaveConfig = {
+  "payments": {
+    "items": {
+      "todos": {
+        "displayName": "Todo Slots",
+        "customerType": "user"
+      }
+    }
+  }
+};`);
+});
+
+import.meta.vitest?.test("parseHexclaveConfigFileContent parses static config exports", ({ expect }) => {
+  expect(parseHexclaveConfigFileContent(`
+    import type { StackConfig } from "@hexclave/js";
+    export const config: StackConfig = {
+      auth: { allowSignUp: true },
+      payments: { testMode: false },
+    };
+  `, "stack.config.ts")).toMatchInlineSnapshot(`
+    {
+      "auth": {
+        "allowSignUp": true,
+      },
+      "payments": {
+        "testMode": false,
+      },
+    }
+  `);
+});
+
+import.meta.vitest?.test("parseHexclaveConfigFileContent parses show-onboarding", ({ expect }) => {
+  expect(parseHexclaveConfigFileContent('export const config = "show-onboarding";', "stack.config.ts")).toBe("show-onboarding");
+});
+
+import.meta.vitest?.test("parseHexclaveConfigFileContent rejects dynamic config exports", ({ expect }) => {
+  expect(() => parseHexclaveConfigFileContent("export const config = makeConfig();", "stack.config.ts")).toThrow(/Unsupported config expression/);
+});
+
+import.meta.vitest?.test("renderConfigFileContent rejects conflicting dotted keys", ({ expect }) => {
+  expect(() => renderConfigFileContent({
+    "a.b": 1,
+    "a.b.c": 2,
+  })).toThrowError(/conflicting keys.*"a\.b\.c"/);
+});
+
+import.meta.vitest?.test("renderConfigFileContent rejects invalid config exports", ({ expect }) => {
+  expect(() => renderConfigFileContent(null)).toThrowErrorMatchingInlineSnapshot(
+    `[Error: Invalid config: expected a plain object.]`,
+  );
+});
+
+import.meta.vitest?.test("renderConfigFileContent uses custom import package", ({ expect }) => {
+  const content = renderConfigFileContent({}, "@hexclave/next");
+  expect(content).toContain('import type { HexclaveConfig } from "@hexclave/next";');
+});
+
+import.meta.vitest?.test("renderConfigFileContent defaults to @hexclave/js", ({ expect }) => {
+  const content = renderConfigFileContent({});
+  expect(content).toContain('import type { HexclaveConfig } from "@hexclave/js";');
+});
+
+import.meta.vitest?.test("detectConfigImportPackage picks first matching package by priority", ({ expect }) => {
+  expect(detectConfigImportPackage(["@hexclave/next", "@hexclave/js"])).toBe("@hexclave/next");
+  expect(detectConfigImportPackage(["@hexclave/react", "@hexclave/js"])).toBe("@hexclave/react");
+  expect(detectConfigImportPackage(["@hexclave/js"])).toBe("@hexclave/js");
+  // Hexclave names take priority over legacy stackframe names when both appear.
+  expect(detectConfigImportPackage(["@stackframe/stack", "@hexclave/next"])).toBe("@hexclave/next");
+  // Legacy fallback still works for projects pinned to the last @stackframe/* release.
+  expect(detectConfigImportPackage(["@stackframe/stack"])).toBe("@stackframe/stack");
+  expect(detectConfigImportPackage(["@stackframe/template"])).toBe("@stackframe/template");
+  expect(detectConfigImportPackage(["lodash", "express"])).toBeUndefined();
+  expect(detectConfigImportPackage([])).toBeUndefined();
+});

package/src/crud.tsx

@@ -0,0 +1,275 @@
+import * as yup from 'yup';
+import { yupObject, yupString } from './schema-fields';
+import { filterUndefined } from './utils/objects';
+import { NullishCoalesce } from './utils/types';
+
+export type AccessType = "client" | "server" | "admin";
+export type CrudOperation = "create" | "read" | "update" | "delete";
+export type CrudlOperation = "create" | "read" | "update" | "delete" | "list";
+export type AccessTypeXCrudOperation = `${AccessType}${Capitalize<CrudOperation>}`;
+export type AccessTypeXCrudlOperation = `${AccessType}${Capitalize<CrudlOperation>}`;
+
+declare module 'yup' {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  export interface CustomSchemaMetadata {
+    openapiField?: {
+      description?: string,
+      exampleValue?: any,
+      hidden?: boolean,
+      onlyShowInOperations?: Capitalize<CrudlOperation>[],
+    },
+  }
+}
+
+type ShownEndpointDocumentation = {
+  summary: string,
+  description: string,
+  tags?: string[],
+  crudOperation?: Capitalize<CrudlOperation>,
+};
+export type EndpointDocumentation =
+  | ({ hidden: true } & Partial<ShownEndpointDocumentation>)
+  | ({ hidden?: boolean } & ShownEndpointDocumentation);
+
+
+type InnerCrudSchema<
+  CreateSchema extends yup.AnySchema | undefined = yup.AnySchema | undefined,
+  ReadSchema extends yup.AnySchema | undefined = yup.AnySchema | undefined,
+  UpdateSchema extends yup.AnySchema | undefined = yup.AnySchema | undefined,
+  DeleteSchema extends yup.AnySchema | undefined = yup.AnySchema | undefined,
+> = {
+  createSchema: CreateSchema,
+  createDocs: EndpointDocumentation | undefined,
+
+  readSchema: ReadSchema,
+  readDocs: EndpointDocumentation | undefined,
+  listDocs: EndpointDocumentation | undefined,
+
+  updateSchema: UpdateSchema,
+  updateDocs: EndpointDocumentation | undefined,
+
+  deleteSchema: DeleteSchema,
+  deleteDocs: EndpointDocumentation | undefined,
+};
+
+export type CrudSchema<
+  ClientSchema extends InnerCrudSchema = InnerCrudSchema,
+  ServerSchema extends InnerCrudSchema = InnerCrudSchema,
+  AdminSchema extends InnerCrudSchema = InnerCrudSchema,
+> = {
+  client: ClientSchema,
+  server: ServerSchema,
+  admin: AdminSchema,
+
+  hasCreate: boolean,
+  hasRead: boolean,
+  hasUpdate: boolean,
+  hasDelete: boolean,
+};
+
+export type CrudSchemaCreationOptions = {
+  [K in AccessTypeXCrudOperation as `${K}Schema`]?: yup.AnySchema
+};
+
+type FillInOptionalsPrepareStep<O extends CrudSchemaCreationOptions> =
+  & { [K in keyof Required<CrudSchemaCreationOptions>]: K extends keyof O ? O[K] : undefined };
+
+type FillInOptionalsStep<O extends FillInOptionalsPrepareStep<CrudSchemaCreationOptions>> = {
+  clientCreateSchema: NullishCoalesce<O['clientCreateSchema'], undefined>,
+  clientReadSchema: NullishCoalesce<O['clientReadSchema'], undefined>,
+  clientUpdateSchema: NullishCoalesce<O['clientUpdateSchema'], undefined>,
+  clientDeleteSchema: NullishCoalesce<O['clientDeleteSchema'], undefined>,
+
+  serverCreateSchema: NullishCoalesce<O['serverCreateSchema'], O['clientCreateSchema']>,
+  serverReadSchema: NullishCoalesce<O['serverReadSchema'], O['clientReadSchema']>,
+  serverUpdateSchema: NullishCoalesce<O['serverUpdateSchema'], O['clientUpdateSchema']>,
+  serverDeleteSchema: NullishCoalesce<O['serverDeleteSchema'], O['clientDeleteSchema']>,
+
+  adminCreateSchema: NullishCoalesce<O['adminCreateSchema'], O['serverCreateSchema']>,
+  adminReadSchema: NullishCoalesce<O['adminReadSchema'], O['serverReadSchema']>,
+  adminUpdateSchema: NullishCoalesce<O['adminUpdateSchema'], O['serverUpdateSchema']>,
+  adminDeleteSchema: NullishCoalesce<O['adminDeleteSchema'], O['serverDeleteSchema']>,
+};
+
+type FillInOptionals<O extends CrudSchemaCreationOptions> = FillInOptionalsStep<FillInOptionalsStep<FillInOptionalsStep<FillInOptionalsPrepareStep<O>>>>;
+
+type CrudSchemaFromOptionsInner<O extends FillInOptionals<any>> = CrudSchema<
+  InnerCrudSchema<O['clientCreateSchema'], O['clientReadSchema'], O['clientUpdateSchema'], O['clientDeleteSchema']>,
+  InnerCrudSchema<O['serverCreateSchema'], O['serverReadSchema'], O['serverUpdateSchema'], O['serverDeleteSchema']>,
+  InnerCrudSchema<O['adminCreateSchema'], O['adminReadSchema'], O['adminUpdateSchema'], O['adminDeleteSchema']>
+>;
+
+export type CrudSchemaFromOptions<O extends CrudSchemaCreationOptions> = CrudSchemaFromOptionsInner<FillInOptionals<O>>;
+
+type InnerCrudTypeOf<S extends InnerCrudSchema> =
+  & (S['createSchema'] extends {} ? { Create: yup.InferType<S['createSchema']> } : {})
+  & (S['readSchema'] extends {} ? { Read: yup.InferType<S['readSchema']> } : {})
+  & (S['updateSchema'] extends {} ? { Update: yup.InferType<S['updateSchema']> } : {})
+  & (S['deleteSchema'] extends {} ? { Delete: yup.InferType<S['deleteSchema']> } : {})
+  & (S['readSchema'] extends {} ? { List: {
+    items: yup.InferType<S['readSchema']>[],
+    is_paginated: boolean,
+    pagination?: {
+      next_cursor: string | null,
+    },
+  }, } : {});
+
+export type CrudTypeOf<S extends CrudSchema> = {
+  Client: InnerCrudTypeOf<S['client']>,
+  Server: InnerCrudTypeOf<S['server']>,
+  Admin: InnerCrudTypeOf<S['admin']>,
+}
+
+type CrudDocsCreationOptions<SO extends CrudSchemaCreationOptions> = {
+  [X in AccessTypeXCrudlOperation]?: EndpointDocumentation
+};
+
+export function createCrud<SO extends CrudSchemaCreationOptions>(options: SO & { docs?: CrudDocsCreationOptions<SO> }): CrudSchemaFromOptions<SO> {
+  const docs = options.docs ?? {};
+  const client = {
+    createSchema: options.clientCreateSchema,
+    createDocs: docs.clientCreate,
+
+    readSchema: options.clientReadSchema,
+    readDocs: docs.clientRead,
+    listDocs: docs.clientList,
+
+    updateSchema: options.clientUpdateSchema,
+    updateDocs: docs.clientUpdate,
+
+    deleteSchema: options.clientDeleteSchema,
+    deleteDocs: docs.clientDelete,
+  };
+
+  const serverOverrides = filterUndefined({
+    createSchema: options.serverCreateSchema,
+    createDocs: docs.serverCreate,
+
+    readSchema: options.serverReadSchema,
+    readDocs: docs.serverRead,
+    listDocs: docs.serverList,
+
+    updateSchema: options.serverUpdateSchema,
+    updateDocs: docs.serverUpdate,
+
+    deleteSchema: options.serverDeleteSchema,
+    deleteDocs: docs.serverDelete,
+  });
+  const server = {
+    ...client,
+    ...serverOverrides,
+  };
+
+  const adminOverrides = filterUndefined({
+    createSchema: options.adminCreateSchema,
+    createDocs: docs.adminCreate,
+
+    readSchema: options.adminReadSchema,
+    readDocs: docs.adminRead,
+    listDocs: docs.adminList,
+
+    updateSchema: options.adminUpdateSchema,
+    updateDocs: docs.adminUpdate,
+
+    deleteSchema: options.adminDeleteSchema,
+    deleteDocs: docs.adminDelete,
+  });
+  const admin = {
+    ...server,
+    ...adminOverrides,
+  };
+
+  return {
+    client: client as any,
+    server: server as any,
+    admin: admin as any,
+
+    hasCreate: !!admin.createSchema,
+    hasRead: !!admin.readSchema,
+    hasUpdate: !!admin.updateSchema,
+    hasDelete: !!admin.deleteSchema,
+  };
+}
+
+import.meta.vitest?.test("createCrud", ({ expect }) => {
+  // Test with empty options
+  const emptyCrud = createCrud({});
+  expect(emptyCrud.hasCreate).toBe(false);
+  expect(emptyCrud.hasRead).toBe(false);
+  expect(emptyCrud.hasUpdate).toBe(false);
+  expect(emptyCrud.hasDelete).toBe(false);
+  expect(emptyCrud.client.createSchema).toBeUndefined();
+  expect(emptyCrud.server.createSchema).toBeUndefined();
+  expect(emptyCrud.admin.createSchema).toBeUndefined();
+
+  // Test with client schemas only
+  const mockSchema = yupObject().shape({
+    name: yupString().defined(),
+  });
+
+  const clientOnlyCrud = createCrud({
+    clientCreateSchema: mockSchema,
+    clientReadSchema: mockSchema,
+  });
+  expect(clientOnlyCrud.hasCreate).toBe(true);
+  expect(clientOnlyCrud.hasRead).toBe(true);
+  expect(clientOnlyCrud.hasUpdate).toBe(false);
+  expect(clientOnlyCrud.hasDelete).toBe(false);
+  expect(clientOnlyCrud.client.createSchema).toBe(mockSchema);
+  expect(clientOnlyCrud.server.createSchema).toBe(mockSchema);
+  expect(clientOnlyCrud.admin.createSchema).toBe(mockSchema);
+
+  // Test with server overrides
+  const serverSchema = yupObject().shape({
+    name: yupString().defined(),
+    internalField: yupString().defined(),
+  });
+
+  const serverOverrideCrud = createCrud({
+    clientCreateSchema: mockSchema,
+    serverCreateSchema: serverSchema,
+  });
+  expect(serverOverrideCrud.hasCreate).toBe(true);
+  expect(serverOverrideCrud.client.createSchema).toBe(mockSchema);
+  expect(serverOverrideCrud.server.createSchema).toBe(serverSchema);
+  expect(serverOverrideCrud.admin.createSchema).toBe(serverSchema);
+
+  // Test with admin overrides
+  const adminSchema = yupObject().shape({
+    name: yupString().defined(),
+    internalField: yupString().defined(),
+    adminField: yupString().defined(),
+  });
+
+  const fullOverrideCrud = createCrud({
+    clientCreateSchema: mockSchema,
+    serverCreateSchema: serverSchema,
+    adminCreateSchema: adminSchema,
+  });
+  expect(fullOverrideCrud.hasCreate).toBe(true);
+  expect(fullOverrideCrud.client.createSchema).toBe(mockSchema);
+  expect(fullOverrideCrud.server.createSchema).toBe(serverSchema);
+  expect(fullOverrideCrud.admin.createSchema).toBe(adminSchema);
+
+  // Test with documentation
+  const crudWithDocs = createCrud({
+    clientCreateSchema: mockSchema,
+    docs: {
+      clientCreate: {
+        summary: "Create a resource",
+        description: "Creates a new resource",
+        tags: ["resources"],
+      },
+    },
+  });
+  expect(crudWithDocs.client.createDocs).toEqual({
+    summary: "Create a resource",
+    description: "Creates a new resource",
+    tags: ["resources"],
+  });
+  expect(crudWithDocs.server.createDocs).toEqual({
+    summary: "Create a resource",
+    description: "Creates a new resource",
+    tags: ["resources"],
+  });
+});

package/src/global.d.ts

@@ -0,0 +1 @@
+import type { } from "react/canary";