• Basics
  • Abyss
  • Web APIs
  • C# & Razor
  • .net API
  • JS & TS API
Search Results for

    Show / Hide Table of Contents

    Convention: Everything is Immutable

    There are many programming paradigms. One that's become very important to us is immutable programming. This is strongly related to functional APIs

    This means than objects inside 2sxc are never modified. Instead, they are copied and modified, and the original object is discarded.

    Example

    
    var original = new { Name = "John", Age = 42 };
    var modified = SomeService.ChangeAge(original, 43);
    
    var areEqual = original.Age == modified.Age; // false
    
    

    Use in DataSources

    A common place where this affects Razor and WebApis is when using DataSources. Old data sources could do this:

    var entityFilter = CreateSource<EntityIdFilter>();
    entityFilter.EntityIds = "123,456";
    var data = entityFilter.List;
    

    This behavior still works on old data sources to ensure compatibility. But newer DataSources such as AppFiles will not allow this, and will throw an exception if you try to modify the properties. They are immutable. Instead, you must do this:

    var appFiles = CreateSource<AppFiles>(options: new { OnlyFolders = true });
    // The following would throw an error:
    // appFiles.OnlyFolders = true;
    var data = appFiles.List;
    

    This new way is the only recommended way of doing this from now on.

    Coverage

    As of March 2023, ca. 80% of all objects in 2sxc are immutable, we hope to reach 95% by end of 2023. We cannot reach 100% any time soon, because we must ensure compatibility with existing code.

    1. IEntity is internally 98% immutable - some details left to optimize
    2. DataSources can be immutable. Newer DataSources are immutable, and data sources created using Kit.Data are immutable by default.

    History

    • First introductions in 2sxc 13
    • Spread out more in 2sxc 15, eg. IEntity is now immutable

    Shortlink: https://go.2sxc.org/immutable

    • Improve this Doc
    In This Article
    Back to top Generated by DocFX