@ai-matrx/records 0.42.0 → 0.43.0

package/dist/react/index.cjs

@@ -67,10 +67,12 @@ __export(react_exports, {
   choiceValuesOf: () => choiceValuesOf,
   choicesOf: () => choicesOf,
   err: () => err,
+  forgetAllOps: () => forgetAllOps,
   highestLevel: () => highestLevel,
   holdsARetiredChoice: () => holdsARetiredChoice,
   indexedDbStore: () => indexedDbStore,
   isDecided: () => isDecided,
+  isOwnOp: () => isOwnOp,
   isRecordsErr: () => isRecordsErr,
   isTheChosen: () => isTheChosen,
   looksLikeAnId: () => looksLikeAnId,
@@ -78,12 +80,14 @@ __export(react_exports, {
   measureKey: () => measureKey,
   memoryStore: () => memoryStore,
   mintClientKey: () => mintClientKey,
+  mintOpId: () => mintOpId,
   ok: () => ok,
   openCaptureQueue: () => openCaptureQueue,
   optionKey: () => optionKey,
   optionLabel: () => optionLabel,
   portalPath: () => portalPath,
   publicFormPath: () => publicFormPath,
+  rememberedOpCount: () => rememberedOpCount,
   scopeChip: () => scopeChip,
   tableShapeChanged: () => tableShapeChanged,
   useEntityFieldMutation: () => useEntityFieldMutation,
@@ -110,6 +114,45 @@ module.exports = __toCommonJS(react_exports);
 // src/react/context.tsx
 var import_react = require("react");
 
+// src/ops.ts
+var REMEMBER_MS = 3e4;
+var REMEMBER_MAX = 500;
+var ours = /* @__PURE__ */ new Map();
+function trim(now) {
+  for (const [id, at] of ours) {
+    if (now - at <= REMEMBER_MS) break;
+    ours.delete(id);
+  }
+  while (ours.size > REMEMBER_MAX) {
+    const oldest = ours.keys().next();
+    if (oldest.done === true) break;
+    ours.delete(oldest.value);
+  }
+}
+function mintOpId() {
+  const id = crypto.randomUUID();
+  const now = Date.now();
+  ours.set(id, now);
+  trim(now);
+  return id;
+}
+function isOwnOp(opId) {
+  if (!opId) return false;
+  const at = ours.get(opId);
+  if (at === void 0) return false;
+  if (Date.now() - at > REMEMBER_MS) {
+    ours.delete(opId);
+    return false;
+  }
+  return true;
+}
+function forgetAllOps() {
+  ours.clear();
+}
+function rememberedOpCount() {
+  return ours.size;
+}
+
 // src/level.ts
 var PERMISSION_LEVELS = [
   "viewer",
@@ -587,6 +630,7 @@ var STORE_DOORS = [
   { name: "read_paths_outside_the_door", args: "", returns: "TABLE(object_name text, why text)", security: "invoker" },
   { name: "read_record", args: "p_organization_id uuid, p_record_id uuid, p_by_id boolean DEFAULT false", returns: "jsonb", security: "definer" },
   { name: "read_records", args: "p_organization_id uuid, p_table_id uuid, p_by_id boolean DEFAULT false, p_limit integer DEFAULT 200, p_offset integer DEFAULT 0", returns: "TABLE(id uuid, document jsonb, level permission_level)", security: "definer" },
+  { name: "read_records_by_ids", args: "p_organization_id uuid, p_table_id uuid, p_record_ids uuid[], p_by_id boolean DEFAULT false", returns: "TABLE(id uuid, document jsonb, level permission_level)", security: "definer" },
   { name: "realtime_topic_admits", args: "p_topic text", returns: "boolean", security: "definer" },
   { name: "record_aggregate", args: "p_organization_id uuid, p_table_id uuid, p_group_by jsonb DEFAULT '[]'::jsonb, p_measures jsonb DEFAULT '[]'::jsonb, p_bucket jsonb DEFAULT NULL::jsonb, p_filter jsonb DEFAULT '{}'::jsonb, p_limit integer DEFAULT 200, p_required text DEFAULT 'viewer'::text", returns: "TABLE(groups jsonb, measures jsonb, row_count bigint)", security: "definer" },
   { name: "record_applicability", args: "p_organization_id uuid, p_record_id uuid", returns: "TABLE(rule_id uuid, rule_name text, rule_version integer, applies boolean, answer jsonb)", security: "invoker" },
@@ -611,6 +655,7 @@ var STORE_DOORS = [
   { name: "record_values", args: "p_organization_id uuid, p_record_id uuid", returns: "jsonb", security: "invoker" },
   { name: "record_values_of", args: "p_row custom.record", returns: "jsonb", security: "invoker" },
   { name: "record_values_versioned", args: "p_organization_id uuid, p_record_id uuid", returns: "TABLE(field_key text, field_id uuid, value jsonb, value_version integer, source jsonb, absent_reason text, actor text, on_behalf_of text, written_at timestamp with time zone, alternates jsonb)", security: "definer" },
+  { name: "record_words", args: "p_organization_id uuid, p_record_id uuid, p_noun text DEFAULT NULL::text", returns: "text", security: "definer" },
   { name: "record_write", args: "p_organization_id uuid, p_table_id uuid, p_data jsonb", returns: "uuid", security: "definer" },
   { name: "record_write_many", args: "p_organization_id uuid, p_table_id uuid, p_rows jsonb[], p_ids uuid[] DEFAULT NULL::uuid[]", returns: "uuid[]", security: "definer" },
   { name: "refusals_claiming_a_level_never_asked", args: "", returns: "TABLE(function_name text, identity_args text, why text)", security: "invoker" },
@@ -811,18 +856,18 @@ var STORE_KNOBS = [
   { key: "world_publish_enabled", value: "false", type: "boolean" }
 ];
 var STORE_REFUSAL_CODES = [
-  { code: "02000", raised_by: "_checklist_instantiate,checklist_declare,checklist_run,checklist_step_complete,checklist_step_refusal,checklist_template_shape,conversation_scope_bind,dashboard_delete,dashboard_run,doc_letterhead,doc_render_body,doc_render_document,doc_render_read,doc_sign,doc_signature_intact,doc_signature_read,doc_template_delete,doc_template_read,doc_template_save,enrich_pin,entity_field_retire,entity_field_update,entity_record_read,entity_value_write,external_history_event,external_rows,external_stub_upsert,external_writes_set,io_restore,migrate_delete,migrate_extract_parent,migrate_merge,migrate_reclass,migrate_rename,migrate_reparent,migrate_retype,migrate_split,migrate_undo,organization_clear,portal_card,portal_declare,portal_invite,portal_preview,portal_principal_bind,portal_revoke,read_record,record_delete,record_restore,record_restore_preview,record_table,record_update,relation_uncarry,share_access,share_grant,share_lane_set,share_people,share_revoke,sign_request_cancel,sign_request_create,sign_request_remind,sign_request_unchanged,table_share_outside_accept,table_share_outside_invite,table_share_outside_resend,table_share_outside_revoke,visibility_as_of,work_approval_decide,work_approval_read,work_approval_request,work_assign,work_record_states,work_set_state" },
+  { code: "02000", raised_by: "_checklist_instantiate,_table_share_invite_payload,checklist_declare,checklist_run,checklist_step_complete,checklist_step_refusal,checklist_template_shape,conversation_scope_bind,dashboard_delete,dashboard_run,doc_letterhead,doc_render_body,doc_render_document,doc_render_read,doc_sign,doc_signature_intact,doc_signature_read,doc_template_delete,doc_template_read,doc_template_save,enrich_pin,entity_field_retire,entity_field_update,entity_record_read,entity_value_write,external_history_event,external_rows,external_stub_upsert,external_writes_set,io_restore,migrate_delete,migrate_extract_parent,migrate_merge,migrate_reclass,migrate_rename,migrate_reparent,migrate_retype,migrate_split,migrate_undo,organization_clear,portal_card,portal_declare,portal_invite,portal_preview,portal_principal_bind,portal_revoke,read_record,record_delete,record_restore,record_restore_preview,record_table,record_update,relation_uncarry,share_access,share_grant,share_lane_set,share_people,share_revoke,sign_request_cancel,sign_request_create,sign_request_remind,sign_request_unchanged,table_share_outside_accept,table_share_outside_invite,table_share_outside_resend,table_share_outside_revoke,visibility_as_of,work_approval_decide,work_approval_read,work_approval_request,work_assign,work_record_states,work_set_state" },
   { code: "0A000", raised_by: "checklist_step_complete,external_rows,external_source_declare,external_write_through,promote_field,promoted_index_expr,promoted_query_sql,promoted_read,rule_eval,work_assign" },
   { code: "22003", raised_by: "context_resolve" },
   { code: "22004", raised_by: "_entity_custom_fields_guard,_value_envelope,actor_word,agg_assert_key,agg_sql,anon_capture,anon_token_issue,anon_write,assert_client_may_reach,booking_declare,capture_submit,checklist_declare,context_resolve,dashboard_block_normalize,dashboard_declare,dashboard_window_sql,doc_render_write,doc_sign,doc_signature_write,doc_template_save,enrich_land,enrich_normalize,external_history_event,external_rows,external_source_declare,external_stub_upsert,external_write_through,external_writes_set,field_history,form_declare,form_submit,home_add,io_comment_write,io_import_begin,io_infer_column,io_outbox_drain,io_restore,migrate_choice_keys,migrate_purge,migrate_reclass,migrate_split,migrate_undo,organization_clear,organization_contents,pipeline_declare,pipeline_gate_preview,portal_declare,portal_invite,portal_principal_bind,provenance_retention_days,provenance_write,query_across_homes,query_by_coordinates,query_rollup,record_delete,record_reparent,record_resolve,record_restore,record_update,record_write,record_write_many,relation_carry,relation_own,rule_declare,share_grant,sign_request_create,sign_request_sign,subscription_declare,table_declare,table_share_outside_invite,value_restore,view_declare,work_approval_decide,work_approval_request,work_template_declare" },
   { code: "22007", raised_by: "dashboard_window_sql" },
   { code: "22012", raised_by: "rule_eval" },
-  { code: "22023", raised_by: "_booking_availability,_entity_custom_fields_guard,_value_envelope,_work_shape_guard,actor_word,agg_assert_key,agg_sql,anon_token_issue,booking_declare,containment_parent,dashboard_block_normalize,dashboard_window_sql,doc_render_body,doc_render_write,doc_signature_write,enrich_declare,enrich_land,enrich_normalize,enrich_pin,entity_value_write,external_history_event,external_source_declare,external_stub_upsert,external_write_through,field_history,io_export,io_import_begin,io_import_finish,io_import_plan,io_import_report,io_proposal_accept,migrate_merge,migrate_reclass,my_levels,organization_clear,page_size,pin_agent_cells,pipeline_move,portal_declare,provenance_write,query_by_coordinates,query_rollup,record_update,record_write_many,relation_carry,rule_eval,rule_members,share_grant,share_lane_set,sign_request_create,sign_request_sign,subscription_declare,table_rules,visibility_as_of,work_approval_request,work_list,work_slot_hold" },
+  { code: "22023", raised_by: "_booking_availability,_entity_custom_fields_guard,_take_op_id,_value_envelope,_work_shape_guard,actor_word,agg_assert_key,agg_sql,anon_token_issue,booking_declare,containment_parent,dashboard_block_normalize,dashboard_window_sql,doc_render_body,doc_render_write,doc_signature_write,enrich_declare,enrich_land,enrich_normalize,enrich_pin,entity_value_write,external_history_event,external_source_declare,external_stub_upsert,external_write_through,field_history,io_export,io_import_begin,io_import_finish,io_import_plan,io_import_report,io_proposal_accept,migrate_merge,migrate_reclass,my_levels,organization_clear,page_size,pin_agent_cells,pipeline_move,portal_declare,provenance_write,query_by_coordinates,query_rollup,record_update,record_write_many,relation_carry,rule_eval,rule_members,share_grant,share_lane_set,sign_request_create,sign_request_sign,subscription_declare,table_rules,visibility_as_of,work_approval_request,work_list,work_slot_hold" },
   { code: "23503", raised_by: "_booking_availability,_checklist_instantiate,_containment_guard,_field_document_for,_pipeline_stage_key,_record_rule_uses,agg_digest_assemble,anon_publish,anon_rate_take,anon_token_issue,anon_write,assert_organization_wall,booking_cancel,booking_confirm,booking_declare,booking_hold,booking_reschedule,capture_publish,checklist_declare,checklist_steps_table,comment_write,dashboard_declare,delete_rule,doc_sign,doc_template_save,enrich_declare,enrich_due,enrich_land,form_declare,form_submit,home_add,inbound_declare,inbound_mail_land,inbound_set,io_comment_write,io_import_begin,io_import_finish,io_import_report,io_import_rows,io_proposal_accept,migrate_demote,migrate_promote,pipeline_board,pipeline_declare,pipeline_move,pipeline_read,pipeline_transition_refusal,promote_field,promote_table,record_applicability,record_reparent,relation_carry,relation_own,resolve_first_match,rule_applies,rule_declare,rule_eval,rule_members,rule_run,sign_request_create,subscription_mute,subscription_preview,view_declare,work_set_state,work_take_assignment,work_template_instantiate" },
   { code: "23505", raised_by: "_unique_rule_holds,doc_sign,doc_signature_write,entity_field_declare,field_declare,home_add,inbound_declare,io_proposal_accept,relation_carry,relation_own,share_grant,sign_request_cancel,sign_request_create,table_share_outside_invite,table_share_outside_resend,work_approval_decide,work_slot_hold" },
-  { code: "23514", raised_by: "_checklist_instantiate,_checklist_step_guard,_containment_guard,_dated_values_guard,_derived_fields,_entity_custom_fields_guard,_field_class_guard,_field_document_for,_field_shape_guard,_field_type_parity_guard,_merge_field_shape_guard,_merge_field_temporal_guard,_promoted_field_cap_guard,_record_rule_uses,_resolve_choice_words,_rule_shape_guard,_rule_topology_guard,_store_relation_edge_names_its_field,_table_columns_word_guard,_table_shape_guard,_undeclared_key_guard,_value_envelope,_work_shape_guard,_workdoors_approval_guard,assert_columns_are_defined,assert_entity_is_organization_scoped,capture_publish,capture_sheet_declare,checklist_declare,checklist_step_complete,doc_sign,doc_signature_write,doc_template_save,entity_field_declare,entity_field_retire,entity_field_update,entity_records_find,entity_table,field_declare,field_retire,field_update,home_add,io_import_rows,migrate_merge,relation_carry,relation_own,sign_request_create,sign_request_sign,table_declare,validate_value_envelope,validate_values,work_set_state,work_slots_declare,work_take_assignment,work_template_instantiate" },
+  { code: "23514", raised_by: "_checklist_instantiate,_checklist_step_guard,_containment_guard,_dated_values_guard,_derived_fields,_entity_custom_fields_guard,_field_class_guard,_field_document_for,_field_shape_guard,_field_type_parity_guard,_merge_field_shape_guard,_merge_field_temporal_guard,_promoted_field_cap_guard,_record_rule_uses,_resolve_choice_words,_rule_shape_guard,_rule_topology_guard,_store_relation_edge_names_its_field,_table_columns_word_guard,_table_shape_guard,_undeclared_key_guard,_value_envelope,_work_shape_guard,_workdoors_approval_guard,assert_columns_are_defined,assert_entity_is_organization_scoped,booking_declare,capture_publish,capture_sheet_declare,checklist_declare,checklist_step_complete,doc_sign,doc_signature_write,doc_template_save,entity_field_declare,entity_field_retire,entity_field_update,entity_records_find,entity_table,field_declare,field_retire,field_update,home_add,io_import_rows,migrate_merge,relation_carry,relation_own,sign_request_create,sign_request_sign,table_declare,validate_value_envelope,validate_values,work_set_state,work_slots_declare,work_take_assignment,work_template_instantiate" },
   { code: "40001", raised_by: "has_visibility_at" },
-  { code: "42501", raised_by: "_doc_render_immutable,_doc_signature_immutable,_field_definition_write,_field_write_door,_rule_definition_write,_store_door,anon_capture,anon_inbound_land,anon_publish,anon_token_issue,anon_token_verify,anon_write,assert_client_may_change,assert_client_may_open,assert_client_may_reach,assert_may_know_table,assert_organization_admin,assert_store_door,booking_confirm,booking_declare,booking_hold,capture_submit,checklist_run,comment_write,conversation_scope_bind,conversation_scope_unbind,enrich_declare,enrich_due,enrich_land,enrich_normalize,entity_field_declare,entity_field_retire,entity_field_update,entity_value_write,external_write_through,form_declare,form_submit,inbound_mail_land,io_comment_resolve,io_comment_write,io_import_begin,io_import_finish,io_restore,migrate_purge,migrate_reclass,my_levels,organization_clear,portal_declare,portal_invitation,portal_invite,portal_principal_bind,promote_table,query_visibility_parity,read_record,read_records,record_table,share_grant,subscription_mute,subscription_preview,table_share_outside_accept,table_share_outside_invite,table_share_outside_resend,visibility_as_of,work_approval_decide,work_approval_read,work_approval_request,work_person" },
+  { code: "42501", raised_by: "_doc_render_immutable,_doc_signature_immutable,_field_definition_write,_field_write_door,_rule_definition_write,_store_door,anon_capture,anon_inbound_land,anon_publish,anon_token_issue,anon_token_verify,anon_write,assert_client_may_change,assert_client_may_open,assert_client_may_reach,assert_may_know_table,assert_organization_admin,assert_store_door,booking_confirm,booking_declare,booking_hold,capture_submit,checklist_run,comment_write,conversation_scope_bind,conversation_scope_unbind,enrich_declare,enrich_due,enrich_land,enrich_normalize,entity_field_declare,entity_field_retire,entity_field_update,entity_value_write,external_write_through,form_declare,form_submit,inbound_mail_land,io_comment_resolve,io_comment_write,io_import_begin,io_import_finish,io_restore,migrate_purge,migrate_reclass,my_levels,organization_clear,portal_declare,portal_invitation,portal_invite,portal_principal_bind,promote_table,query_visibility_parity,read_record,read_records,read_records_by_ids,record_table,share_grant,subscription_mute,subscription_preview,table_share_outside_accept,table_share_outside_invite,table_share_outside_resend,visibility_as_of,work_approval_decide,work_approval_read,work_approval_request,work_person" },
   { code: "42703", raised_by: "entity_table,portal_declare" },
   { code: "53400", raised_by: "anon_rate_take,delete_cascade_closure,enrich_due,enrich_land,promote_field" },
   { code: "54001", raised_by: "record_delete" },
@@ -1905,6 +1950,13 @@ var DOORS = {
   // this person could see.
   readRecord: "read_record",
   readRecords: "read_records",
+  // THE SAME READ DOOR, ADDRESSED BY AN ID SET. A realtime notice names the exact ids that
+  // moved; before this existed the only door that took them was the PAGE door, so a
+  // three-cell change re-read fifty rows in every watching browser. It is a separate NAME
+  // rather than a sixth argument to `read_records` because adding a defaulted argument to a
+  // live Postgres function makes every existing call ambiguous — `is not unique`. Same
+  // ladder, same level, same masking, same page ceiling.
+  readRecordsByIds: "read_records_by_ids",
   // DOOR-8, the two clocks. `p_recorded_at` is what the store SAID then;
   // `p_world_on` is what was TRUE of the world on that date, read out of dated
   // values. A client that answered either one itself would be guessing.
@@ -2481,17 +2533,18 @@ function createRecordsClient(config) {
     async recordWrite({ table_id, data }) {
       return callDoor(
         DOORS.recordWrite,
-        { p_organization_id: org, p_table_id: table_id, p_data: data },
+        { p_organization_id: org, p_table_id: table_id, p_data: { ...data, _op_id: mintOpId() } },
         "recordWrite"
       );
     },
     async recordWriteMany({ table_id, rows, ids }) {
+      const opId = mintOpId();
       return callDoor(
         DOORS.recordWriteMany,
         {
           p_organization_id: org,
           p_table_id: table_id,
-          p_rows: rows,
+          p_rows: rows.map((row) => ({ ...row, _op_id: opId })),
           ...ids === void 0 ? {} : { p_ids: ids }
         },
         "recordWriteMany"
@@ -2503,7 +2556,7 @@ function createRecordsClient(config) {
         {
           p_organization_id: org,
           p_record_id: record_id,
-          p_patch: patch,
+          p_patch: { ...patch, _op_id: mintOpId() },
           ...expectedVersion === void 0 ? {} : { p_expected_version: expectedVersion }
         },
         "recordUpdate"
@@ -2545,6 +2598,21 @@ function createRecordsClient(config) {
       }
       return ok({ record_id, document, hidden, computed, computedUnavailable });
     },
+    async listByIds({ table_id, ids }) {
+      if (ids.length === 0) return ok([]);
+      const door = await callDoor(
+        DOORS.readRecordsByIds,
+        { p_organization_id: org, p_table_id: table_id, p_record_ids: ids },
+        "listByIds"
+      );
+      if (!door.ok) return err(door.error);
+      return ok(
+        (door.data ?? []).map((row) => {
+          const { document, hidden } = unfold(row.document);
+          return { id: row.id, document, level: row.level, hidden };
+        })
+      );
+    },
     async list({ table_id, limit = 50, offset = 0 }) {
       const door = await callDoor(
         DOORS.readRecords,
@@ -4263,7 +4331,11 @@ function useAsync(run, deps) {
     };
   }, [client, nonce, ...deps]);
   const reload = (0, import_react2.useCallback)(() => setNonce((n) => n + 1), []);
-  return { ...state, reload };
+  const setData = (0, import_react2.useCallback)((update) => {
+    if (!alive.current) return;
+    setState((s) => ({ ...s, data: update(s.data) }));
+  }, []);
+  return { ...state, reload, setData };
 }
 function useTable(tableId) {
   return useAsync(
@@ -4352,14 +4424,49 @@ function useRecords(tableId, options = {}) {
     [tableId, pageSize, page]
   );
   const realtime = client.config.realtime;
-  const { reload } = base;
+  const { reload, setData } = base;
   (0, import_react2.useEffect)(() => {
     if (!realtime || !tableId) return;
     return realtime.subscribeRecords(
       { organization_id: client.config.organizationId, table_id: tableId },
-      () => reload()
+      {
+        records(ids) {
+          if (ids === null) {
+            void reload();
+            return;
+          }
+          if (ids.length === 0) return;
+          void (async () => {
+            const answered = await client.listByIds({ table_id: tableId, ids });
+            if (!answered.ok) {
+              void reload();
+              return;
+            }
+            const fresh = new Map(answered.data.map((row) => [row.id, row]));
+            const onThisPage = (id) => (base.data?.rows ?? []).some((row) => row.id === id);
+            const needsThePage = ids.some((id) => !onThisPage(id) && fresh.has(id));
+            if (needsThePage) {
+              void reload();
+              return;
+            }
+            setData(
+              (current) => current === null ? current : {
+                ...current,
+                // A named id that came back replaces the row on screen; one that did NOT
+                // is a record this reader may no longer see (deleted, or unshared), so it
+                // leaves the page — exactly what the page read would have done by
+                // omission.
+                rows: current.rows.filter((row) => !(ids.includes(row.id) && !fresh.has(row.id))).map((row) => fresh.get(row.id) ?? row)
+              }
+            );
+          })();
+        },
+        shape() {
+          if (tableId) tableShapeChanged(tableId);
+        }
+      }
     );
-  }, [realtime, tableId, client.config.organizationId, reload]);
+  }, [realtime, tableId, client, reload, setData, base.data]);
   const live = Boolean(realtime && tableId);
   const liveReason = realtime ? tableId ? "Live: changes to this table re-read through the read door." : "Not live: no table selected." : "Not live: this host bound no realtime port, so this list updates when you reload it.";
   return { ...base, live, liveReason };