jazz-tools 0.19.12 → 0.19.14

package/src/tools/implementation/createContext.ts

@@ -28,10 +28,39 @@ export type Credentials = {
   secret: AgentSecret;
 };
 
-type SessionProvider = (
-  accountID: ID<Account>,
-  crypto: CryptoProvider,
-) => Promise<{ sessionID: SessionID; sessionDone: () => void }>;
+export interface SessionProvider {
+  acquireSession: (
+    accountID: ID<Account>,
+    crypto: CryptoProvider,
+  ) => Promise<{ sessionID: SessionID; sessionDone: () => void }>;
+  persistSession: (
+    accountID: ID<Account>,
+    sessionID: SessionID,
+  ) => Promise<{ sessionDone: () => void }>;
+}
+
+export class MockSessionProvider implements SessionProvider {
+  async acquireSession(
+    accountID: ID<Account>,
+    crypto: CryptoProvider,
+  ): Promise<{ sessionID: SessionID; sessionDone: () => void }> {
+    return {
+      sessionID: crypto.newRandomSessionID(
+        accountID as unknown as RawAccountID,
+      ),
+      sessionDone: () => {},
+    };
+  }
+
+  async persistSession(
+    _accountID: ID<Account>,
+    _sessionID: SessionID,
+  ): Promise<{ sessionDone: () => void }> {
+    return {
+      sessionDone: () => {},
+    };
+  }
+}
 
 export type AuthResult =
   | {
@@ -57,16 +86,6 @@ export type AuthResult =
       logOut: () => Promise<void>;
     };
 
-export async function randomSessionProvider(
-  accountID: ID<Account>,
-  crypto: CryptoProvider,
-) {
-  return {
-    sessionID: crypto.newRandomSessionID(accountID as unknown as RawAccountID),
-    sessionDone: () => {},
-  };
-}
-
 export type JazzContextWithAccount<Acc extends Account> = {
   node: LocalNode;
   account: Acc;
@@ -107,7 +126,7 @@ export async function createJazzContextFromExistingCredentials<
   storage?: StorageAPI;
   asActiveAccount: boolean;
 }): Promise<JazzContextWithAccount<InstanceOfSchema<S>>> {
-  const { sessionID, sessionDone } = await sessionProvider(
+  const { sessionID, sessionDone } = await sessionProvider.acquireSession(
     credentials.accountID,
     crypto,
   );
@@ -167,6 +186,7 @@ export async function createJazzContextForNewAccount<
   AccountSchema: PropsAccountSchema,
   onLogOut,
   storage,
+  sessionProvider,
 }: {
   creationProps: { name: string };
   initialAgentSecret?: AgentSecret;
@@ -175,6 +195,7 @@ export async function createJazzContextForNewAccount<
   AccountSchema?: S;
   onLogOut?: () => Promise<void>;
   storage?: StorageAPI;
+  sessionProvider: SessionProvider;
 }): Promise<JazzContextWithAccount<InstanceOfSchema<S>>> {
   const CurrentAccountSchema =
     PropsAccountSchema ?? (RegisteredSchemas["Account"] as unknown as S);
@@ -199,11 +220,17 @@ export async function createJazzContextForNewAccount<
   const account = AccountClass.fromNode(node);
   activeAccountContext.set(account);
 
+  const { sessionDone } = await sessionProvider.persistSession(
+    account.$jazz.id,
+    node.currentSessionID,
+  );
+
   return {
     node,
     account: account as InstanceOfSchema<S>,
     done: () => {
       node.gracefulShutdown();
+      sessionDone();
     },
     logOut: async () => {
       node.gracefulShutdown();
@@ -270,6 +297,7 @@ export async function createJazzContext<
       peers: options.peers,
       crypto,
       AccountSchema: options.AccountSchema,
+      sessionProvider: options.sessionProvider,
       onLogOut: async () => {
         await authSecretStorage.clearWithoutNotify();
       },

package/src/tools/implementation/schema.ts

@@ -5,9 +5,14 @@ import {
   type CoValue,
   type CoValueClass,
   CoValueFromRaw,
+  extendContainerOwner,
   Group,
+  type GroupRole,
   ItemsSym,
   LoadedAndRequired,
+  type NewInlineOwnerStrategy,
+  type RefOnCreateCallback,
+  type RefPermissions,
   SchemaInit,
   isCoValueClass,
 } from "../internal.js";
@@ -94,31 +99,33 @@ export const coField = {
 
 function optionalRef<C extends CoValueClass>(
   arg: C | ((raw: InstanceType<C>["$jazz"]["raw"]) => C),
+  options: { permissions: RefPermissions },
 ): InstanceType<C> | null | undefined {
-  return ref(arg, { optional: true });
+  return ref(arg, { optional: true, permissions: options.permissions });
 }
 
 function ref<C extends CoValueClass>(
   arg: C | ((raw: InstanceType<C>["$jazz"]["raw"]) => C),
-  options?: never,
+  options: { permissions?: RefPermissions },
 ): InstanceType<C> | null;
 function ref<C extends CoValueClass>(
   arg: C | ((raw: InstanceType<C>["$jazz"]["raw"]) => C),
-  options: { optional: true },
+  options: { optional: true; permissions?: RefPermissions },
 ): InstanceType<C> | null | undefined;
 function ref<
   C extends CoValueClass,
-  Options extends { optional?: boolean } | undefined,
+  Options extends { optional?: boolean; permissions?: RefPermissions },
 >(
   arg: C | ((raw: InstanceType<C>["$jazz"]["raw"]) => C),
-  options?: Options,
+  options: Options,
 ): Options extends { optional: true }
   ? InstanceType<C> | null | undefined
   : InstanceType<C> | null {
   return {
     [SchemaInit]: {
       ref: arg,
-      optional: options?.optional || false,
+      optional: options.optional || false,
+      permissions: options.permissions,
     } satisfies Schema,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   } as any;
@@ -129,6 +136,7 @@ export type EncodedAs<V> = { encoded: Encoder<V> | OptionalEncoder<V> };
 export type RefEncoded<V extends CoValue> = {
   ref: CoValueClass<V> | ((raw: RawCoValue) => CoValueClass<V>);
   optional: boolean;
+  permissions?: RefPermissions;
 };
 
 export function isRefEncoded<V extends CoValue>(
@@ -158,24 +166,26 @@ export function instantiateRefEncodedFromRaw<V extends CoValue>(
  *
  * @param schema - The schema of the CoValue to create.
  * @param init - The init values to use to create the CoValue.
- * @param parentOwner - The owner of the referencing CoValue. Will be used
- * as the parent group of the created CoValue's group
+ * @param containerOwner - The owner of the referencing CoValue. Will be used
+ * to determine the owner of the new CoValue
+ * @param newOwnerStrategy - The strategy to use to determine the owner of the new CoValue
+ * @param onCreate - The callback to call when the new CoValue is created
  * @returns The created CoValue.
  */
 export function instantiateRefEncodedWithInit<V extends CoValue>(
   schema: RefEncoded<V>,
   init: any,
-  parentOwner: Group,
+  containerOwner: Group,
+  newOwnerStrategy: NewInlineOwnerStrategy = extendContainerOwner,
+  onCreate?: RefOnCreateCallback,
 ): V {
   if (!isCoValueClass<V>(schema.ref)) {
     throw Error(
       `Cannot automatically create CoValue from value: ${JSON.stringify(init)}. Use the CoValue schema's create() method instead.`,
     );
   }
-  const node = parentOwner.$jazz.localNode;
-  const rawGroup = node.createGroup();
-  const owner = new Group({ fromRaw: rawGroup });
-  owner.addMember(parentOwner);
+  const owner = newOwnerStrategy(() => Group.create(), containerOwner, init);
+  onCreate?.(owner, init);
   // @ts-expect-error - create is a static method in all CoValue classes
   return schema.ref.create(init, owner);
 }

package/src/tools/implementation/schemaUtils.ts

@@ -1,4 +1,4 @@
-import { CoreResolveQuery } from "./zodSchema/schemaTypes/CoValueSchema";
+import { CoreResolveQuery } from "./zodSchema/schemaTypes/CoValueSchema.js";
 
 /**
  * Remove getters from an object

package/src/tools/implementation/zodSchema/runtimeConverters/schemaFieldToCoFieldDef.ts

@@ -1,8 +1,24 @@
 import type { JsonValue } from "cojson";
-import { CoValueClass, isCoValueClass } from "../../../internal.js";
+import {
+  CoValueClass,
+  isCoValueClass,
+  schemaToRefPermissions,
+  getDefaultRefPermissions,
+  SchemaPermissions,
+  RefPermissions,
+  type NewInlineOwnerStrategy,
+  type CoreCoDiscriminatedUnionSchema,
+  type DiscriminableCoValueSchemas,
+  type RefOnCreateCallback,
+} from "../../../internal.js";
 import { coField } from "../../schema.js";
 import { CoreCoValueSchema } from "../schemaTypes/CoValueSchema.js";
-import { isUnionOfPrimitivesDeeply } from "../unionUtils.js";
+import {
+  isUnionOfPrimitivesDeeply,
+  getFlattenedUnionOptions,
+  getDiscriminatorValuesForOption,
+  resolveDiscriminantValue,
+} from "../unionUtils.js";
 import {
   ZodCatch,
   ZodDefault,
@@ -76,17 +92,28 @@ export function schemaFieldToCoFieldDef(schema: SchemaField): CoFieldDef {
   }
 
   if (isCoValueClass(schema)) {
-    return cacheSchemaField(schema, coField.ref(schema));
+    return cacheSchemaField(
+      schema,
+      coField.ref(schema, {
+        permissions: getDefaultRefPermissions(),
+      }),
+    );
   } else if (isCoValueSchema(schema)) {
     if (schema.builtin === "CoOptional") {
       return cacheSchemaField(
         schema,
         coField.ref(schema.getCoValueClass(), {
           optional: true,
+          permissions: schemaFieldPermissions(schema),
         }),
       );
     }
-    return cacheSchemaField(schema, coField.ref(schema.getCoValueClass()));
+    return cacheSchemaField(
+      schema,
+      coField.ref(schema.getCoValueClass(), {
+        permissions: schemaFieldPermissions(schema),
+      }),
+    );
   } else {
     if ("_zod" in schema) {
       const zodSchemaDef = schema._zod.def;
@@ -228,3 +255,77 @@ export function schemaFieldToCoFieldDef(schema: SchemaField): CoFieldDef {
     }
   }
 }
+
+function schemaFieldPermissions(schema: CoreCoValueSchema): RefPermissions {
+  if (schema.builtin === "CoOptional") {
+    return schemaFieldPermissions((schema as any).innerType);
+  }
+  if (schema.builtin === "CoDiscriminatedUnion") {
+    return discriminatedUnionFieldPermissions(
+      schema as CoreCoDiscriminatedUnionSchema<DiscriminableCoValueSchemas>,
+    );
+  }
+  return "permissions" in schema
+    ? schemaToRefPermissions(schema.permissions as SchemaPermissions)
+    : getDefaultRefPermissions();
+}
+
+function discriminatedUnionFieldPermissions(
+  schema: CoreCoDiscriminatedUnionSchema<DiscriminableCoValueSchemas>,
+): RefPermissions {
+  const discriminatorKey = schema.getDefinition().discriminator;
+  const allOptions = getFlattenedUnionOptions(schema);
+
+  const valueToStrategy = new Map<unknown, RefPermissions>();
+  for (const option of allOptions) {
+    const optionPermissions = schemaFieldPermissions(option);
+    const discriminatorValues = getDiscriminatorValuesForOption(
+      option,
+      discriminatorKey,
+    );
+
+    if (!discriminatorValues) {
+      continue;
+    }
+
+    for (const value of discriminatorValues) {
+      if (!valueToStrategy.has(value)) {
+        valueToStrategy.set(value, optionPermissions);
+      }
+    }
+  }
+
+  const fallbackStrategy = getDefaultRefPermissions();
+
+  const newInlineOwnerStrategy: NewInlineOwnerStrategy = (
+    createNewGroup,
+    containerOwner,
+    init,
+  ) => {
+    const discriminantValue = resolveDiscriminantValue(init, discriminatorKey);
+    const strategy =
+      discriminantValue !== undefined
+        ? valueToStrategy.get(discriminantValue)
+        : undefined;
+
+    const effectiveStrategy = strategy ?? fallbackStrategy;
+    return effectiveStrategy.newInlineOwnerStrategy(
+      createNewGroup,
+      containerOwner,
+      init,
+    );
+  };
+
+  const onCreate: RefOnCreateCallback = (newGroup, init) => {
+    const discriminantValue = resolveDiscriminantValue(init, discriminatorKey);
+    const strategy =
+      discriminantValue !== undefined
+        ? valueToStrategy.get(discriminantValue)
+        : undefined;
+
+    const effectiveStrategy = strategy ?? fallbackStrategy;
+    effectiveStrategy.onCreate?.(newGroup, init);
+  };
+
+  return { newInlineOwnerStrategy, onCreate };
+}

package/src/tools/implementation/zodSchema/schemaPermissions.ts

@@ -0,0 +1,188 @@
+import { Account, Group, TypeSym, type GroupRole } from "../../internal.js";
+
+/**
+ * Defines how a nested CoValue’s owner is obtained when creating CoValues from JSON.
+ *
+ * This configuration is not used when using an explicit .create() for nested CoValues.
+ * In that case, {@link SchemaPermissions.default} is used.
+ */
+export type OnInlineCreateOptions =
+  /**
+   * Always create a new group for CoValues created inline
+   */
+  | "newGroup"
+  /**
+   * Use the same owner as the container CoValue
+   */
+  | "sameAsContainer"
+  /**
+   * Create a new group that includes the container CoValue's owner as a member (effectively inheriting
+   * all permissions from the container)
+   */
+  | "extendsContainer"
+  /**
+   * Similar to "extendsContainer", but allows overriding the role of the container CoValue's owner
+   */
+  | { extendsContainer: GroupRole }
+  /**
+   * Create a new group and configure it as needed
+   */
+  | InlineGroupConfigurationCallback;
+
+export type InlineGroupConfigurationCallback = (
+  newGroup: Group,
+  context: { containerOwner: Group },
+) => void;
+
+export type OnCreateCallback = (newGroup: Group) => void;
+
+/**
+ * Internal callback type used by RefPermissions that includes init for discriminated union support.
+ * @internal
+ */
+export type RefOnCreateCallback = (newGroup: Group, init?: unknown) => void;
+
+/**
+ * Permissions to be used when creating or composing CoValues
+ * @param default - default owner to be used when creating a CoValue without providing an explicit owner.
+ * @param onInlineCreate - defines how a nested CoValue's owner is obtained when creating CoValues from JSON.
+ * @param onCreate - callback that runs every time a CoValue is created. Can be used to configure the CoValue's owner.
+ * Runs both when creating CoValues with `.create()` and when creating CoValues from JSON.
+ * @default { default: () => Group.create(), onInlineCreate: "extendsContainer" }
+ */
+export type SchemaPermissions = {
+  /**
+   * default owner to be used when creating a CoValue without providing an explicit owner.
+   */
+  default?: () => Group;
+  /**
+   * Defines how a nested CoValue's owner is obtained when creating CoValues from JSON.
+   */
+  onInlineCreate?: OnInlineCreateOptions;
+  /**
+   * callback that runs every time a CoValue is created. Can be used to configure the CoValue's owner.
+   * Runs both when creating CoValues with `.create()` and when creating CoValues from JSON.
+   */
+  onCreate?: OnCreateCallback;
+};
+
+export let DEFAULT_SCHEMA_PERMISSIONS: SchemaPermissions = {
+  default: () => Group.create(),
+  onInlineCreate: "extendsContainer",
+};
+
+/**
+ * Update the default schema permissions for all new CoValue schemas.
+ * Schemas created before calling this function will not be affected.
+ */
+export function setDefaultSchemaPermissions(permissions: SchemaPermissions) {
+  DEFAULT_SCHEMA_PERMISSIONS = {
+    ...DEFAULT_SCHEMA_PERMISSIONS,
+    ...permissions,
+  };
+}
+
+/**
+ * Parsed {@link SchemaPermissions}, used by CoValue classes to set up permissions for referenced CoValues.
+ */
+export type RefPermissions = {
+  newInlineOwnerStrategy: NewInlineOwnerStrategy;
+  onCreate?: RefOnCreateCallback;
+};
+
+/**
+ * A function that creates a new owner for a new CoValue created inline.
+ * @param createNewGroup - A function that creates a new group.
+ * @param containerOwner - The owner of the container CoValue.
+ * @param init - The value used to create the new CoValue. Necessary to determine the concrete
+ * strategy to use in discriminated unions.
+ * @returns The new owner.
+ */
+export type NewInlineOwnerStrategy = (
+  createNewGroup: () => Group,
+  containerOwner: Group,
+  init?: unknown,
+) => Group;
+
+export const extendContainerOwnerFactory =
+  (roleOverride?: GroupRole): NewInlineOwnerStrategy =>
+  (createNewGroup: () => Group, containerOwner: Group): Group => {
+    const node = containerOwner.$jazz.localNode;
+    const rawGroup = node.createGroup();
+    const owner = new Group({ fromRaw: rawGroup });
+    owner.addMember(containerOwner, roleOverride);
+    return owner;
+  };
+
+/**
+ * A function that creates a new owner for a new CoValue by extending the container CoValue's owner
+ * (without overriding its role)
+ */
+export const extendContainerOwner = extendContainerOwnerFactory();
+
+export function schemaToRefPermissions(
+  permissions: SchemaPermissions,
+): RefPermissions {
+  const newInlineOwnerStrategy = parseOnInlineCreate(
+    permissions.onInlineCreate,
+  );
+  const onCreate: RefOnCreateCallback | undefined = permissions.onCreate
+    ? (newGroup, _init) => permissions.onCreate?.(newGroup)
+    : undefined;
+  return {
+    newInlineOwnerStrategy,
+    onCreate,
+  };
+}
+
+function parseOnInlineCreate(
+  onInlineCreate?: OnInlineCreateOptions,
+): NewInlineOwnerStrategy {
+  if (!onInlineCreate || onInlineCreate === "extendsContainer") {
+    return extendContainerOwner;
+  }
+  if (
+    typeof onInlineCreate === "object" &&
+    "extendsContainer" in onInlineCreate
+  ) {
+    return extendContainerOwnerFactory(onInlineCreate.extendsContainer);
+  }
+  if (onInlineCreate === "newGroup") {
+    return (createNewGroup) => createNewGroup();
+  }
+  if (onInlineCreate === "sameAsContainer") {
+    return (_createNewGroup, containerOwner) => containerOwner;
+  }
+  return (createNewGroup, containerOwner) => {
+    const newGroup = createNewGroup();
+    onInlineCreate(newGroup, { containerOwner });
+    return newGroup;
+  };
+}
+
+export function getDefaultRefPermissions(): RefPermissions {
+  return schemaToRefPermissions(DEFAULT_SCHEMA_PERMISSIONS);
+}
+
+export function withSchemaPermissions<T extends { owner?: Account | Group }>(
+  options?: T | Account | Group,
+  schemaPermissions?: SchemaPermissions,
+): T & { onCreate?: OnCreateCallback } {
+  const onCreate = schemaPermissions?.onCreate;
+  if (!options) {
+    const owner = schemaPermissions?.default?.() ?? Group.create();
+    return { owner, onCreate } as T & { onCreate?: OnCreateCallback };
+  }
+  if (TypeSym in options) {
+    return { owner: options, onCreate } as T & {
+      onCreate?: OnCreateCallback;
+    };
+  }
+  const owner =
+    options.owner ?? schemaPermissions?.default?.() ?? Group.create();
+  return {
+    ...options,
+    owner,
+    onCreate,
+  } as T & { onCreate?: OnCreateCallback };
+}

package/src/tools/implementation/zodSchema/schemaTypes/CoFeedSchema.ts

@@ -4,6 +4,7 @@ import {
   BranchDefinition,
   CoFeed,
   Group,
+  hydrateCoreCoValueSchema,
   Settled,
   RefsToResolve,
   RefsToResolveStrict,
@@ -12,6 +13,7 @@ import {
   coOptionalDefiner,
   parseSubscribeRestArgs,
   unstable_mergeBranchWithResolve,
+  withSchemaPermissions,
 } from "../../../internal.js";
 import { AnonymousJazzAgent } from "../../anonymousJazzAgent.js";
 import { CoFeedSchemaInit } from "../typeConverters/CoFieldSchemaInit.js";
@@ -20,6 +22,10 @@ import { InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded } from "../typeConverter
 import { CoOptionalSchema } from "./CoOptionalSchema.js";
 import { CoreCoValueSchema, CoreResolveQuery } from "./CoValueSchema.js";
 import { withSchemaResolveQuery } from "../../schemaUtils.js";
+import {
+  DEFAULT_SCHEMA_PERMISSIONS,
+  SchemaPermissions,
+} from "../schemaPermissions.js";
 
 export class CoFeedSchema<
   T extends AnyZodOrCoValueSchema,
@@ -36,6 +42,12 @@ export class CoFeedSchema<
    */
   resolveQuery: DefaultResolveQuery = true as DefaultResolveQuery;
 
+  /**
+   * Permissions to be used when creating or composing CoValues
+   * @internal
+   */
+  permissions: SchemaPermissions = DEFAULT_SCHEMA_PERMISSIONS;
+
   constructor(
     public element: T,
     private coValueClass: typeof CoFeed,
@@ -54,7 +66,14 @@ export class CoFeedSchema<
     init: CoFeedSchemaInit<T>,
     options?: { owner: Account | Group } | Account | Group,
   ): CoFeedInstance<T> {
-    return this.coValueClass.create(init as any, options) as CoFeedInstance<T>;
+    const optionsWithPermissions = withSchemaPermissions(
+      options,
+      this.permissions,
+    );
+    return this.coValueClass.create(
+      init as any,
+      optionsWithPermissions,
+    ) as CoFeedInstance<T>;
   }
 
   load<
@@ -146,8 +165,32 @@ export class CoFeedSchema<
   >(
     resolveQuery: RefsToResolveStrict<CoFeedInstanceCoValuesMaybeLoaded<T>, R>,
   ): CoFeedSchema<T, R> {
-    const copy = new CoFeedSchema<T, R>(this.element, this.coValueClass);
-    copy.resolveQuery = resolveQuery as R;
+    return this.copy({ resolveQuery: resolveQuery as R });
+  }
+
+  /**
+   * Configure permissions to be used when creating or composing CoValues
+   */
+  withPermissions(
+    permissions: SchemaPermissions,
+  ): CoFeedSchema<T, DefaultResolveQuery> {
+    return this.copy({ permissions });
+  }
+
+  private copy<ResolveQuery extends CoreResolveQuery = DefaultResolveQuery>({
+    permissions,
+    resolveQuery,
+  }: {
+    permissions?: SchemaPermissions;
+    resolveQuery?: ResolveQuery;
+  }): CoFeedSchema<T, ResolveQuery> {
+    const coreSchema = createCoreCoFeedSchema(this.element);
+    // @ts-expect-error
+    const copy: CoFeedSchema<T, ResolveQuery> =
+      hydrateCoreCoValueSchema(coreSchema);
+    // @ts-expect-error TS cannot infer that the resolveQuery type is valid
+    copy.resolveQuery = resolveQuery ?? this.resolveQuery;
+    copy.permissions = permissions ?? this.permissions;
     return copy;
   }
 }