feat: createContexts

[wjmelements]

Supercedes #325
Toward #312
Reviewers @rvagg @hugomrdias

As this is not yet the blessed path, I don't update the examples from createContext to createContexts.

Changes

• CreateContextsOptions
• createWithSelectedProvider
• createContexts
• mockServiceProviderRegistry helper
• tests

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	synapse-dev	877f4ed	Commit Preview URL Branch Preview URL	Nov 04 2025, 12:32 AM

[hugomrdias]

why can this be more simple like:

user knows what he wants

type ProviderDatasetPair {
  providerId: bigint
  datasetId: bigint | undefined // create new dataset in this provider
}

createContexts(pairs: ProviderDatasetPair[], options: createDatasetOptions)

smart selection

type Options {
  excludeProviderIds?: number []
  withCDN?: boolean
  withIpni?: boolean
  dev?: boolean
  forceCreateDataSet?: boolean
  uploadBatchSize?: number
  metadata?: Record<string, string>
}

createSmartContexts(options: Options) // its auto and smart

[hugomrdias]

why not just force options?.dataSetIds.length to equal options.count ?

[hugomrdias]

humm because its selecting providers...

[wjmelements]

datasetId: bigint | undefined // create new dataset in this provider

This isn't our behavior for createContext. createContext will prefer to use existing data sets when they match the criteria, even if providerId or providerAddress is provided. Smart selection also does that, but for all providers.

[hugomrdias]

datasetId: bigint | undefined // create new dataset in this provider

This isn't our behavior for createContext. createContext will prefer to use existing data sets when they match the criteria, even if providerId or providerAddress is provided. Smart selection also does that, but for all providers.

sure we can the same and not force the create dataset if its undefined

[wjmelements]

type ProviderDatasetPair {
  providerId: bigint
  datasetId: bigint | undefined // create new dataset in this provider
}

I've thought about this a bit, and while the priority is more implicit, I think the interface is slightly better without this intermediate ProviderDatasetPair. Compare:

createContexts({
    dataSetIds,
})
createContexts({
    providerIds,
})
// vs ProviderDatasetPair
createContexts({
    selections: dataSetIds.map((dataSetId) => { dataSetId }),
})
createContexts({
    selections: providerIds.map((providerId) => { providerId }),
})

I would also be interested in @rvagg's opinion on this. It's not too important to me but after we make this interface public it will be painful to change it.

createSmartContexts

I don't think we need multiple methods since both will fallback to smart selection. It's sufficient for me that the specification parameters are optional.

[rvagg]

Sorry, I'm not a fan of ProviderDatasetPair - mainly because I think they are joining two separate user behaviours:

1. I want to make multiple contexts from my list of pre-selected providers - I may or may not have data sets for these, you figure it out
2. I have existing data sets and I just want contexts for those - don't make me remember the providers, data set ID is globally unique, that's all I should need to keep, you just need to figure it out, don't need to create them, just set it up for me

That second path I think is the most interesting one and the one we want to make sure works - perhaps data set IDs get persisted in a cookie for a dapp user, every time they come back they always just get those same data sets that were created for them the first time they used it.

Every other bit of optionality is advanced use I think.

[wjmelements]

Unable to merge

[rvagg]

I'm fine with override-and-fix since we have release-please standing in the way of releases. If @hugomrdias would like to propose an alternative diff then let's get that in before we cut a release. Sorry Hugo, let's keep moving and fix stuff later if we discover the API isn't all that great.