Merge pull request #2618 from garden-co/fix/inspector-element

fix: simplify definition of the AccountSchema type

Author: gdorsi

.changeset/modern-bulldogs-dance.md

@@ -0,0 +1,5 @@
+---
+"jazz-tools": patch
+---
+
+Refactor AccountSchema types to solve "This is likely not portable. A type annotation is necessary" issue when using co.account()

packages/jazz-tools/src/tools/exports.ts

@@ -102,6 +102,8 @@ export {
   type InstanceOfSchemaCoValuesNullable,
   type CoValueOrZodSchema,
   type Loaded,
+  type BaseAccountShape,
+  type DefaultAccountShape,
   type AccountSchema,
   type AnyAccountSchema,
   type CoListSchema,

packages/jazz-tools/src/tools/implementation/zodSchema/schemaTypes/AccountSchema.ts

@@ -7,22 +7,24 @@ import { z } from "../zodReExport.js";
 import { Loaded, ResolveQuery } from "../zodSchema.js";
 import { AnyCoMapSchema, CoMapSchema } from "./CoMapSchema.js";
 
+export type BaseProfileShape = {
+  name: z.core.$ZodString<string>;
+  inbox?: z.core.$ZodOptional<z.core.$ZodString>;
+  inboxInvite?: z.core.$ZodOptional<z.core.$ZodString>;
+};
+
+export type BaseAccountShape = {
+  profile: AnyCoMapSchema<BaseProfileShape>;
+  root: AnyCoMapSchema;
+};
+
+export type DefaultAccountShape = {
+  profile: CoMapSchema<BaseProfileShape>;
+  root: CoMapSchema<{}>;
+};
+
 export type AccountSchema<
-  Shape extends {
-    profile: AnyCoMapSchema<{
-      name: z.core.$ZodString<string>;
-      inbox?: z.core.$ZodOptional<z.core.$ZodString>;
-      inboxInvite?: z.core.$ZodOptional<z.core.$ZodString>;
-    }>;
-    root: AnyCoMapSchema;
-  } = {
-    profile: CoMapSchema<{
-      name: z.core.$ZodString<string>;
-      inbox?: z.core.$ZodOptional<z.core.$ZodString>;
-      inboxInvite?: z.core.$ZodOptional<z.core.$ZodString>;
-    }>;
-    root: CoMapSchema<{}>;
-  },
+  Shape extends BaseAccountShape = DefaultAccountShape,
 > = Omit<CoMapSchema<Shape>, "create" | "load" | "withMigration"> & {
   builtin: "Account";
 

packages/jazz-tools/src/tools/implementation/zodSchema/zodCo.ts

@@ -1,22 +1,23 @@
 import {
   type Account,
-  AccountCreationProps,
-  AccountSchema,
-  AnyCoMapSchema,
+  type AccountCreationProps,
+  type AccountSchema,
+  type AnyCoMapSchema,
+  BaseAccountShape,
   CoFeed,
-  CoFeedSchema,
-  CoListSchema,
-  CoMapSchema,
+  type CoFeedSchema,
+  type CoListSchema,
+  type CoMapSchema,
   CoPlainText,
-  CoProfileSchema,
-  CoRecordSchema,
+  type CoProfileSchema,
+  type CoRecordSchema,
   CoRichText,
-  DefaultProfileShape,
+  type DefaultProfileShape,
   FileStream,
-  FileStreamSchema,
+  type FileStreamSchema,
   ImageDefinition,
-  PlainTextSchema,
-  Simplify,
+  type PlainTextSchema,
+  type Simplify,
   zodSchemaToCoSchema,
 } from "../../internal.js";
 import { RichTextSchema } from "./schemaTypes/RichTextSchema.js";
@@ -82,16 +83,9 @@ export const coMapDefiner = <Shape extends z.core.$ZodLooseShape>(
   return enrichCoMapSchema(objectSchema);
 };
 
-function enrichAccountSchema<
-  Shape extends {
-    profile: AnyCoMapSchema<{
-      name: z.core.$ZodString<string>;
-      inbox?: z.core.$ZodOptional<z.core.$ZodString>;
-      inboxInvite?: z.core.$ZodOptional<z.core.$ZodString>;
-    }>;
-    root: AnyCoMapSchema;
-  },
->(schema: z.ZodObject<Shape, z.core.$strip>) {
+function enrichAccountSchema<Shape extends BaseAccountShape>(
+  schema: z.ZodObject<Shape, z.core.$strip>,
+) {
   const enrichedSchema = Object.assign(schema, {
     collaborative: true,
     builtin: "Account",
@@ -142,16 +136,44 @@ function enrichAccountSchema<
   return enrichedSchema;
 }
 
-export const coAccountDefiner = <
-  Shape extends {
-    profile: AnyCoMapSchema<{
-      name: z.core.$ZodString<string>;
-      inbox?: z.core.$ZodOptional<z.core.$ZodString>;
-      inboxInvite?: z.core.$ZodOptional<z.core.$ZodString>;
-    }>;
-    root: AnyCoMapSchema;
-  },
->(
+/**
+ * Defines a collaborative account schema for Jazz applications.
+ *
+ * Creates an account schema that represents a user account with profile and root data.
+ * Accounts are the primary way to identify and manage users in Jazz applications.
+ *
+ * @template Shape - The shape of the account schema extending BaseAccountShape
+ * @param shape - The account schema shape. Defaults to a basic profile with name, inbox, and inboxInvite fields, plus an empty root object.
+ *
+ * @example
+ * ```typescript
+ * // Basic account with default profile
+ * const BasicAccount = co.account();
+ *
+ * // Custom account with specific profile and root structure
+ * const JazzAccount = co.account({
+ *   profile: co.profile({
+ *     name: z.string(),
+ *     avatar: z.optional(z.string()),
+ *   }),
+ *   root: co.map({
+ *     organizations: co.list(Organization),
+ *     draftOrganization: DraftOrganization,
+ *   }),
+ * }).withMigration(async (account) => {
+ *   // Migration logic for existing accounts
+ *   if (account.profile === undefined) {
+ *     const group = Group.create();
+ *     account.profile = co.profile().create(
+ *       { name: getRandomUsername() },
+ *       group
+ *     );
+ *     group.addMember("everyone", "reader");
+ *   }
+ * });
+ * ```
+ */
+export const coAccountDefiner = <Shape extends BaseAccountShape>(
   shape: Shape = {
     profile: coMapDefiner({
       name: z.string(),